ETO Development Tools 4

home *** CD-ROM | disk | FTP | other *** search

/ ETO Development Tools 4 / ETO Development Tools 4.iso / Essentials / MPW 411 / MPWHelp < prev next >

Wrap

Text File | 1991-04-08 | 364.5 KB | 10,428 lines | [TEXT/MPS ]

æKY CopyrightNotice æC Copyright Apple Computer, Inc. 1986-1991, All rights reserved. 411 - MPW Help - MPW 3.2 Final Release. Thursday, April 4, 1991 11:53:46 AM MPW 3.2 Help Summaries Help information is available for each of the MPW commands. To see the list of commands select Help and type command - 1. In addition, brief descriptions of Expressions, Patterns, Selections, Characters, Shortcuts, Variables, and Projector are also included. To see Help summaries, Select one of the following and type command - 1 a commandName # information about commandName Commands # a list of commands Expressions # summary of expressions Patterns # summary of patterns (regular expressions) Selections # summary of selections Characters # summary of MPW Shell special characters Shortcuts # summary of MPW Shell shortcuts Variables # summary of the standard MPW shell variables Projector # summary of Projector, a project/source control system Copyright Apple Computer, Inc. 1986-1990 All rights reserved. æKY Commands æC MPW Commands -- A list of MPW executable commands AddMenu # add a menu item AddPane # split the window into panes Adjust # adjust lines Alert # display an alert box Alias # define or write command aliases Align # align text to left margin Asm # MC68xxx Macro Assembler Backup # folder file backup Beep # generate tones Begin # group commands Break # break from For or Loop Browser # invoke Marker Browser BuildCommands # show build commands BuildMenu # create the Build menu BuildProgram # build the specified program C # C compiler Canon # canonical spelling tool Catenate # concatenate files CFront # C++ to C translator CheckIn # check a file into a project CheckOut # check a file out from a project CheckOutDir # specify the directory where checked out files will placed Choose # choose or list network file server volumes and printers Clear # clear the selection Close # close specified windows CMarker # generate Mark commands for C and C++ function definitions Commando # present a dialog interface for commands Compare # compare text files CompareFiles # compare text files and interactively view differences CompareRevisions# compare two revisions of a file in a project Confirm # display a confirmation dialog box Continue # continue with next iteration of For or Loop Copy # copy selection to Clipboard Count # count lines and characters CPlus # script to compile C++ source CreateMake # create a simple makefile Cut # copy selection to Clipboard and delete it Date # write the date and time Delete # delete files and directories DeleteMenu # delete user-defined menus and menu items DeleteNames # delete user-defined symbolic names DeletePane # delete panes from the window DeleteRevisions # delete previous revisions of files in a project DeRez # resource decompiler Directory # set or write the default directory DirectoryMenu # create the Directory menu DoIt # highlight and execute a series of shell commands DumpCode # write formatted CODE resources DumpFile # display contents of any file DumpObj # write formatted object file Duplicate # duplicate files and directories Echo # echo parameters Eject # eject volumes Entab # convert runs of spaces to tabs Equal # compare files and directories Erase # initialize volumes Evaluate # evaluate an expression Execute # execute command file in the current scope Exists # confirm the existence of a file or directory Exit # exit from a command file Export # make variables available to commands FileDiv # divide a file into several smaller files Files # list files and directories Find # find and select a text pattern Flush # flush the tools that the Shell has cached For # repeat commands once per parameter Format # set or display formatting options for a window Get # get information about a key word from a data file GetErrorText # display error messages based on message number GetFileName # display a Standard File dialog box GetListItem # display items for selection in a dialog box Help.MPW # write summary information If # conditional command execution Lib # combine object files into a library file Line # find line in the target window Link # link an application, tool, or resource Loop # repeat commands until Break Make # build up-to-date version of a program MakeErrorFile # create error message textfile Mark # assign a marker to a selection Markers # list markers MatchIt # semi-intelligent language sensitive bracket matcher MergeBranch # merge a branch revision onto the trunk ModifyReadOnly # enables a read-only Projector file to be edited Mount # mount volumes MountProject # mount projects Move # move files and directories MoveWindow # move window to h,v location NameRevisions # define a symbolic name New # open a new window Newer # compare modification dates of files NewFolder # create a new folder NewProject # create a new project Open # open file(s) in window(s) OrphanFiles # remove Projector information from a list of files Parameters # write parameters Pascal # Pascal compiler PasMat # Pascal programs formatter PasRef # Pascal cross-referencer Paste # replace selection with Clipboard contents PerformReport # generate a performance report Position # display current line position Print # print text files ProcNames # display Pascal procedure and function names Project # set or write the current project ProjectInfo # display information about a Project Quit # quit MPW Quote # echo parameters, quoting if needed Rename # rename files and directories Replace # replace the selection Request # request text from a dialog box ResEqual # compares the resources in two files Revert # revert window to previous saved state Rez # resource compiler RezDet # detect inconsistencies in resources RotateWindows # send active (frontmost) window to back Save # save specified windows SaveOnClose # set save behavior when closing windows Search # search files for pattern Set # define or write Shell variables SetDirectory # set the default directory SetFile # set file attributes SetPrivilege # set access privileges for directories on file servers SetVersion # maintain version and revision number Shift # renumber command file positional parameters ShowSelection # place the selection within an editor window Shutdown # power down or restart the machine SizeWindow # set a window's size Sort # sort or merge lines of text StackWindows # arrange windows diagonally StreamEdit # scriptable text editor Target # make a window the target window TileWindows # arrange windows in a tiled fashion TransferCkid # move Projector information from one file to another Translate # translate characters Unalias # remove aliases Undo # undo the last edit Unexport # remove variable definitions from the export list Unmark # remove a marker from a window Unmount # unmount volumes UnmountProject # unmount projects Unset # remove Shell variable definitions UserVariables # uses Commando to set all the user variables Version # print the version of the MPW Shell Volumes # list mounted volumes WhereIs # find the location of a file Which # determine which file the shell will execute Windows # list windows ZoomWindow # enlarge or reduce a window's size æKY Help MPWHelp æKL About411 Characters Commands Expressions Patterns Projector Selections Shortcuts Variables AddMenu AddPane Adjust Alert Alias Align Asm Backup Beep Begin Break BuildCommands BuildMenu BuildProgram C Canon Catenate CFront CheckIn CheckOut CheckOutDir Choose Clear Close CMarker Commando Compare CompareFiles CompareRevisions Confirm Continue Copy Count CPlus CreateMake Cut Date Delete DeleteMenu DeleteNames DeletePane DeleteRevisions DeRez Directory DirectoryMenu DoIt DumpCode DumpFile DumpObj Duplicate Echo Eject Entab Equal Erase Evaluate Execute Exists Exit Export FileDiv Files Find Flush For Format Get GetErrorText GetFileName GetListItem Help.MPW If Lib Line Link Loop Make MakeErrorFile Mark Markers MatchIt MergeBranch ModifyReadOnly Mount MountProject Move MoveWindow NameRevisions New Newer NewFolder NewProject Open OrphanFiles Parameters Pascal PasMat PasRef Paste PerformReport Position Print ProcNames Project ProjectInfo Quit Quote Rename Replace Request ResEqual Revert Rez RezDet RotateWindows Save SaveOnClose Search Set SetDirectory SetFile SetPrivilege SetVersion Shift ShowSelection Shutdown SizeWindow Sort StackWindows StreamEdit Target TileWindows TransferCkid Translate Unalias Undo Unexport Unmark Unmount UnmountProject Unset UserVariables Version Volumes WhereIs Which Windows ZoomWindow æKY Variables æC Variables defined by the MPW Shell: {Active} full pathname of current active window {Aliases} list of all defined aliases {Boot} volume name of the boot disk {Command} full pathname of the last command executed {MPW} full pathname of the Macintosh Programmer's Workshop. {ShellDirectory} full pathname of the directory that contains the MPW Shell {Status} result of the last command executed (0 means successful) {SystemFolder} full pathname of the system folder {Target} full pathname of the target window {User} the current user name (initialized to the "Chooser" name) {Windows} list of current windows {Worksheet} full pathname of the Worksheet window Variables used by the MPW Shell: {Commando} name of the commando tool {Commands} list of directories to search for commands {DirectoryPath} list of common directories to speed changing directories {Echo} control the echoing of commands to diagnostic output {Exit} control script termination based on {Status} {IgnoreCmdPeriod} control use of cmd-. during critical sections {HideHelpKey} deactivate "help" key on extended keyboard {Test} control execution of tools and applications {AutoIndent} auto indent setting used for new windows {CaseSensitive} control case sensitivity for searching {Font} font used for new windows {FontSize} font size used for new windows {NewWindowRect} window rectangle used for new windows (top,left,bottom,right) {PrintOptions} options used by the print menu commands {SearchBackward} control direction of searching {SearchType} control type of searching (literal/word/expression) {SearchWrap} control wrap-around search {StackOptions} options used by the Stack Windows menu command {Tab} tab size used for new windows {TileOptions} options used by the Tile Windows menu command {WordSet} set of characters that constitue a word {ZoomWindowRect} window rectangle used for a zoomed window (top,left,bottom,right) Variables automatically set before script execution: {0} name of the currently executing script {1}, {2}, … {n} first, second, and nth parameter to the script {#} number of parameters {Parameters} equivalent to {1} {2} … {n} {"Parameters"} equivalent to "{1}" "{2}" … "{n}" Variables used for libraries and include files: {AIncludes} directories to search for assemby-language include files {CIncludes} directories to search for C include files {CLibraries} directory containing C library files {Libraries} directory containing shared library files {PInterfaces} directory containing Pascal interface files {PLibraries} directory containing Pascal library files {RIncludes} directory containing Rez include files æKY Characters æC The characters listed below have special meanings in the command language. Space Space separates words. Tab Tab also separates words. Return Return separates commands. ; Semicolon also separates commands. | Pipe separates commands and pipes output to input. && And separates commands, executing second if first succeeds. || Or separates commands, executing second if first fails. (…) Parenthesis group commands. Parenthesis also group characters in filename patterns. # Comment begins comments. ∂ Escape (Option-D) quotes the following character. '…' Single quote quotes all other characters. "…" Double quote quotes all characters except ∂, {, and `. /…/ Slash quotes all characters except ∂, {, and `. \…\ Backslash quotes all characters except ∂, {, and `. {…} Braces denote variable substitution. `…` Backquotes denote command substitution. ? Question mark matches any character in filename patterns. ≈ Approximately (Option-X) matches any string in patterns. […] Brackets enclose character sets in filename patterns. * Star indicates zero or more repetitions in patterns. + Plus indicates one or more repetitions in patterns. «…» European quotes (Option-\ and Option-Shift-\) enclose repeat counts. < Less-than indicates an input file specification. > Greater-than indicates an output file specification. >> Indicates appending to an output file specification. ≥ Greater-than-or-equal indicates a diagnostic specification. ≥≥ Indicates appending to a diagnostic file specification. ∑ Capital sigma (option-w) indicates both an output file and diagnostic output file specification. ∑∑ Indicates appending to the output and diagnostic file specification. … Elipsis (Option-;) signals the Shell to use Commando æKY Expressions æC Expressions Numbers may be expressed in decimal, hexadecimal, octal, or binary. Any of the following formats may be used: [0-9]+ decimal number 0x[0-9a-f]+ hexadecimal number $[0-9a-f]+ hexadecimal number 0[0-7]+ octal number 0b[01]+ binary number The operators listed below are used in expressions in the Evaluate, If, Else If, Break, Continue, and Exit commands. Alternate spellings of several operators are provided. All of the operators are evaluated from left to right. Operators with the highest precedence are listed first, and operators in the same group have equal precedence. (…) expression grouping - unary negation ~ bitwise negation ! NOT ¬ logical NOT (¬ is Option-L) * multiplication ÷ DIV division (÷ is Option-/) % MOD modulus division + addition - subtraction << shift left >> shift right < less than <= ≤ less than or equal to (≤ is Option-<) > greater than >= ≥ greater than or equal to (≥ is Option->) == equal != <> ≠ not equal (≠ is Option-=) =~ equal to a pattern !~ not equal to a pattern & bitwise AND ^ bitwise XOR | bitwise OR && AND logical AND || OR logical OR æKY Selections æC Selections - selections specify a selection or insertion point § current selection (Option-6) n line number n !n line n lines after end of current selection ¡n line n lines before start of selection (Option-1) position position (defined below) markerName selection marked by markerName pattern pattern (defined below) (selection) selection grouping selection:selection both selections and everything in between position - positions specify an insertion point • position before first character of file (Option-8) ∞ position after last character of file (Option-5) Δselection position before first character of selection (Option-J) selectionΔ position after last character of selection (Option-J) selection!n position n characters after selection selection¡n position n characters before selection (Option-!) pattern - patterns specify characters to be matched /entireRE/ regular expression - search forward \entireRE\ regular expression - search backward Help Patterns # See "Help Patterns" for more information. æKY Patterns æC Patterns - Patterns specify characters to be matched /entireRE/ regular expression - search forward \entireRE\ regular expression - search backward entireRE •RE regular expression at beginning of line (Option-8) RE∞ regular expression at end of line (Option-5) RE regular expression RE simpleExpr simple regular expression - defined below (RE)®digit tagged RE - refer to match as ®digit (Option-R) 'string' literal - no characters within '…' are special "string" literal - only ∂, {, and ` are special within "…" RE1RE2 regular expression RE1 followed by RE2 simpleExpr (RE) regular expression grouping charExpr single character regular expression - defined below simpleExpr* simple expression zero or more times simpleExpr+ simple expression one of more times simpleExpr«n» simple expression n times (Option-\, Option-Shift-\) simpleExpr«n,» simple expression at least n times simpleExpr«n1,n2» simple expression at least n1, at most n2 times charExpr character character (unless it has special meaning) ∂character character - defeats any special meaning (Option-D) ? any character except Return ≈ zero or more characters, except Return (Option-X) [charList] any character in the list [¬charList] any character not in the list (Option-L) charList [ [ first in the list represents itself ] ] first in the list represents itself - - first in the list represents itself character character charList character list of characters character-character character range (e.g. A-Z) æKY ShortCuts æC The following is a list of MPW Shell shortcuts: Double click select word Triple click select line Double Clicking on any of the characters (,),[,],{,},',",/,\,` will select everything between the character and its mate. UpArrow move insertion point one line above current position DownArrow move insertion point one line below current position RightArrow move insertion point one character to the right LeftArrow move insertion point one character to the left Opt-LeftArrow move insertion point one word to the left Opt-RightArrow move insertion point one word to the right Cmd-UpArrow move insertion point up one screen size Cmd-DownArrow move insertion point down one screen size Cmd-RightArrow move insertion point to end of current line Cmd-LeftArrow move insertion point to beginning of current line Cmd-Opt-UpArrow move insertion point to beginning of file Cmd-Opt-DownArrow move insertion point to end of file For the above eight shortcuts, use of the Shift key changes the action from "move" to "extend selection." E.g., Cmd-Shift-Opt RightArrow means "extend selection to end of line." Delete delete character to the left Clear delete character to the right Opt-Delete delete word to the left Opt-Clear delete word to the right Cmd-Delete delete from current position to end of line Cmd-Clear delete from current position to beginning of line Cmd-Opt-Delete delete from current position to end of file Cmd-OptClear delete from current position to beginnning of file Searching shortcuts Cmd-Shift-G reverse the direction of "Find Same" Cmd-Shift-H reverse the direction of "Find Selection" Cmd-Shift-T reverse the direction of "Replace Same" Holding down Shift while selecting OK will reverse the direction of "Find" and "Find and Replace" Holding down Option while selecting "Tile Windows" or "Stack Windows" will include the worksheet in the tiling or stacking Holding down Option while pressing Return will disable auto-indent for that line. Holding down Option while pressing Enter will invoke Commando on that command line. In Dialogs without an EditText item Y Yes N No CMD . Cancel ESC Cancel æKY Projector æC Projector is a collection of built–in MPW commands and windows that help programmers (both individuals and teams) control and account for changes to all the files (documentation, source, applications etc.) associated with a software project. Here is a brief summary of the commands (the CheckIn, CheckOut, and NewProject commands also have windows that can be opened using the "-w" option to the respective command): CheckIn # check a file into a project CheckOut # check a file out from a project CheckOutDir # specify the directory where checked out files will placed CompareRevisions # compare two revisions of a file in a project DeleteNames # delete user-defined symbolic names DeleteRevisions # delete previous revisions of files in a project MergeBranch # merge a branch revision onto the trunk ModifyReadOnly # enables a read-only Projector file to be edited MountProject # mount projects NameRevisions # define a symbolic name NewProject # create a new project OrphanFiles # remove Projector information from a list of files Project # set or write the current project ProjectInfo # display information about a Project TransferCkid # move Projector information from one file to another UnmountProject # unmount projects Examples The command Project causes the current project name to be written to standard output. To change the current project to OurProject, use Project OurProject See also NewProject, MountProject. æKY About411 æC About "411" "411" provides a way for Macintosh developers to achieve rapid retrieval of software development information while using Apple's MPW development system. The access can be via menus and command keys or from command line entries. The software development information includes language-specific Inside Macintosh documentation, Tech Notes, MPW command descriptions and Resource information. In addition a facility for automatic insertion of Toolbox call templates is provided. "411" can also be customized and extended and new information can be added. The help files of "411" may be either local or on a shared file server. Setting up "411" "411" consists of a installation instructions file (Read Me First), a special UserStartup script (UserStartup•Help), an installation script (Install411), and a set of help files along with their .index and .wIndex files. It makes use of a new MPW tool, Get, which was written to support "411" but can be used independently. The "411" folder holds the help files, their index and cross reference index files and a "Tools" folder. An important decision to make in setting up "411" is whether to place the "411" Help files on a server or on your local hard disk. Since these files are large (over 16 Meg total) some thought should go into deciding which files to use and whether to transfer them to your hard disk or, if you are connected to a network, to a file server. The most obvious candidate for removal is either CIncludesHelp or PInterfacesHelp. If you are not developing in both C and Pascal, one of them will probably not be needed. Less obvious, but more significant canidates for removal are the .wIndex files. These files are not required but significantly speeds up the cross reference search done when selecting the 'Search' menu item. Placing the help files on a local hard disk will provide better access speed but will use significant disk space. If you have access to a file server and several persons want to access "411" Help, it may be best to move the "411" folder to the file server. Set up "411" by writing the following two commands to your MPW WorkSheet and executing them: <rls>:Install411 <info> Execute "{ShellDirectory}"UserStartup•Help where <rls> denotes the path to the "411" files on the release medium and <info> denotes the volume on which the user wishes the "411" Help files to reside. If <info> is omitted, the installation will be to the volume that begins the path <rls>. (In this latter case, the data files are not duplicated because they are already residing in the desired place.) For example, if "411" were to be released in a folder named 411Stuff on a CD named MPW 3.2 Release, and the user wanted "411" to be installed on a volume named HelpMe, then the commands to be executed would read: 'MPW 3.2 Release:411Stuff:Install411' HelpMe: Execute "{ShellDirectory}"UserStartup•Help The effect of the first of the above commands is to create the folder HelpMe:411: and to copy to it all of the "411" files. It then, additionally, copies the new Get tool to the user’s MPW Tools folder, copies UserStartup•Help to the MPW folder, and creates a folder called Help Folder in the MPW folder. This latter folder contains at this time a file called Help_Folder whose contents is the single line: HelpMe:411:, i.e. the name of the folder containing the "411" information. The effect of the second of the above commands is to add the "411" menu to the menu bar, and to add one more file to the Help Folder, a file called Help_Files which contains the names of all of the "411" data files in the order in which they will be interrogated, e.g.: HelpMe:411:CIncludesHelp HelpMe:411:InsideMacintoshHelp HelpMe:411:MPWHelp HelpMe:411:PInterfacesHelp HelpMe:411:ResourcesHelp HelpMe:411:TechNotesHelp NOTE: Because the cross reference (.wIndex) files are so large they are not installed automatically. If you want to use these files just drag their icon to the desired folder. Using the "411" Help menu "411" works only from within the MPW development environment. When "411" is properly set up, there should be a 411 menu on the MPW menu bar. If there has been no change to the UserStartup•Help script, the Help menu looks like this: 411 Menu Directory Build 411 ________________________________________________ HD:MPW:Worksheet | Contents | __________________________| Look up CMD-E | | Template CMD-1 | | Show Keys | | Search | |____________________| | Set First File ...| | Set 411 Files ...| | Edit 411 Files ...| |____________________| | About 411 ... | |____________________| The menu items Look up and Template search all of the files listed in Help_Files; the items Contents, Show Keys, and Search look only at the first file in the Help_Files list. This first file is known as the currently selected file. It can be changed by using the Set First File menu item. Contents This menu item lets you see a list of the Help file’s table of contents. For example, if the CIncludesHelp file is the currently selected Help file, then selecting the "Contents" menu item, causes a list of the ToolBox managers to appear in the Help window. ———————————————————————————————————————————————————————————————————————— HelpMe:411:CIncludesHelp Look up… "Help" ———————————————————————————————————————————————————————————————————————— Appletalk.h FixMath.h Palettes.h Serial.h Controls.h Fonts.h Perf.h ShutDown.h CursorCtl.h Globals Picker.h Slots.h Desk.h Graf3D.h Printing.h Sound.h Deskbus.h HyperXCmd.h Quickdraw.h Start.h ... Note that you can obtain the same information by selecting the key word "Help" (or the name of the help file, e.g. CIncludesHelp) and then selecting the Look up menu item. Look up (Command-E) This menu item lets you look up information stored in the help files; the search starts with the currently selected file (See Set First File...). For example, if you choose (see 2 below) the word FindWindow and then select the Look up menu item (or type Command-E) the following information will appear in the Help window: ------------------------------------------------------------------------ HelpMe:411:CIncludesHelp Look up… "findwindow" ------------------------------------------------------------------------ short findwindow(Point *thePoint,WindowPtr *theWindow); Type: Function File {CIncludes}Windows.h Trap Number A92C InsideMacintosh Reference: FindWindow function I-287, P-35, 114, 170 FindWindow procedure V-208 [Macintosh Plus, Macintosh SE, Macintosh II] When a mouse-down event occurs, the application should call FindWindow with thePt equal to the point where the mouse button was pressed (in global coordinates, as ... Thus, to get help for a given key word: 1) Choose the Help file you want information from by using the Set First File... menu item to make the desired file the first file (currently selected file) in the help file list. (Skip this step if the help file is already selected, or if the order of search does not matter.) 2) Click on a word in the active window. You may want to type in the word you want to look up instead. If the item is just one word, it will be automatically selected if the insertion point is adjacent to or within the word. Only if a multiple word item is to be looked up is it necessary to do a manual selection of the entire item. (Note: the means you don’t have to double-click. Also you don’t have to type the entire word, just enough letters to allow 411 to distinguish between the word you want and any other in the current Help file.) 3) Select the menu item Look up or type Command-E. This triggers a search through the help files, in the order in which they are listed, looking for the selected key word. If the search is successful then a window named Help (a file in the MPW directory) is opened and the information associated with the key word is displayed, along with an indication of the file in which the key word was found. Remember, the Look up menu item simply looks for the current selection in the active window. Since numbers are keywords only in TechNotesHelp, selecting a number will retrieve the Macintosh Technical note of that number. The header, which is placed above the "Contents" information, shows the help file that was used. To the right of the file name is a message indicating the key word on which the search was made. A mark is set to this (selected) key word in the file Help to aid the user in subsequent scanning of Help for previously gathered information. A slight modification of UserStartup•Help causes the header to list all the "411" files in the order in which they are searched, with the words on the right (Look up…) printed on the line bearing the name of the file in which the item was actually found. (See Customizing "411" below.) Template (Command-1) This menu item lets you replace a toolbox function call such as FindWindow with the template for that function. For example if you were to select "FindWindow" and choose the 'Template' menu item (or type Command-1), then your "FindWindow" selection in the Active window would be replaced by: short myVariable = findwindow((Point *)thePoint,(WindowPtr *)theWindow); Both C and Pascal templates are available. Use Set First File... on the 411 menu to choose a language by selecting either CIncludesHelp or PInterfacesHelp. Show keys… This menu item lets you list all of the keys in the currently selected help file which begin with the word you have selected in the Request dialog. For example, selecting this menu and then typing the two letters "fs" when CIncludesHelp is your current (first listed) help file, produces a list of all of the HFS calls that begin with "FS", i.e. FSClose, ... Search… This menu item lets you search the currently selected help file for all occurrences of the word you have selected. The result is a list of names (keys) whose data records contain the word. On a large Help file, e.g. CIncludesHelp, this can take a minute or more. Only the current (first listed) help file is searched even if no data record containing the word is found. If your help folder contains a cross reference (.wIndex) file for the Help file the time to search a file is reduced to several seconds. Set First File… This menu item lets you choose a help file to be the currently selected file. A dialog window shows a list of all help files, and you are invited to make a selection. The selected file then becomes the first file in the list that appears in the file Help_Files. It is then known as the currently selected file, and, until you again reorder the list, is the initial target of all Look up, Template, and Contents requests, and the only file used by Show Keys and Search. The Help window opens, displaying the contents list of the selected file. Set 411 Files… This menu item presents a standard file dialog from which to locate a help folder. If a help folder is selected then all the files in the folder that end in the word help are placed in the list of files to search (in Help_Files). Note that this will remove any existing files from the list.. Edit 411 Files This menu item open the Help_Files window, which contains a list of all the help files that "411" knows about. The list may be edited and then saved. Note that each line specifies a path to a single help file. About 411… This menu item displays the credits and then does a lookup in the MPWHelp file for the key "About411". Customizing "411" There are several ways in which "411" can be customized by modifying the UserStartup•Help script: • If you are using a file server and want the script to call the MPW Choose tool to mount the file server when MPW is launched, set the script variables Help_Server and Guest. Set the former to the desired zone:server:volume pathname, and set the latter to 1 if want to log onto the server as an AppleShare "guest.". Note: This requires the Choose tool from MPW 3.2 or later. • If you wish to add or change command keys in the menu, simply edit the AddMenu commands in the UserStartup•Help script. For example, the line AddMenu 411 "Look up/1" in the script could be changed to: AddMenu 411 "Look up/7" to change the function key to Command-7. Alternatively, AddMenu 411 "Look up" removes the function key associated with the Look up menu item entirely. • If you wish to change the name of the "411" menu, modify the argument of the AddMenu command. For example, you can change the menu name "411" to "MyMenu" by changing all occurrences of AddMenu 411... to AddMenu MyMenu... in the UserStartup•Help script. • If you wish all help files to be listed in the header, change the script so that it sets the value of the variable headerStyle to -h (the default is -h2). Using the Get Tool The retrieval of information through the "411" Help menu is based upon calls to the MPW Get tool. The calls that are used by "411" can be seen in the file UserStartup•Help. If you choose, you may instead call the Get tool directly or from your own script. (See the section on Get in the MPW 3.2 B1 Tools/Scripts Release Notes.) Adding your own help to "411" Help files used by the Get tool are ordinary MPW Shell document files whose names end with "Help" and that have an internal organization which is recognized by the Get tool. The requirements are that a Help file consists of a set of records, each record in turn consisting of one or more fields. Each record must start with the field tag æKY ("æ" is option-') followed by one or more words separated by carriage returns. The search of the help file is made on the key words. All other fields are various categories of information to be retrieved. Field tags must be the first item on a line, and are separated from the following material by one or more spaces. Field tags are case sensitive. Each field is terminated by the appearance of a new field tag. The record is terminated by the next æKY tag (or end of file). Example: æKY Key1 Key2 Key3 æC This is a comment The various tags other than æKY are used to put the information to be retrieved into categories. The most neutral of them is æC, which is used for general textual matter. These tags in some cases modify the behavior of Get. For example, the tag æDT, which is used for templates, precedes data which will be retrieved if and only if Get is called with the -t option. This is used in the implementation of the "template" menu item. Other tags cause some boiler plate to be emitted prior to the text in the data base. For example, the tag æRI is used for fields that contain chapter and page references to Inside Macintosh. The text following the field tag will have inserted before it the cosmetic text: "InsideMacintosh Reference:". Field Tag Codes: æKY Key word or set of key words separated by carriage returns. This field denotes the beginning of a "411" record and the words in this field are the record's names, i.e. the words used as keys for retrieval of the record’s data. æKL Key word List . This is typically used in conjunction with the key "Help" to list, as a table of contents, all of the key words in the file. æFa File name of Assembler include file. æFc File name of C header file. æFp File name of Pascal Interface file. æF Used for the names of files which are not interfaces. æT Type of the item: function/structure/constant/etc. æD Formal declaration of the item: function, procedure, or structure. æDT A template for calls of procedures and functions. æC Commentary. This is general textual information, generally lengthy compared to that associated with the other tags. æR Reference to… Used for references other than to Tech Notes and Inside Macintosh. æRI Reference to Inside Macintosh. This is usually a chapter and page reference. æRT Reference to Tech Note. This is usually a reference by number. æTN Trap Number. This is used to annotate function that are in-line trap calls. æMM Routine may move or purge memory. This tag cause issuance of the preceding warning. When the Get tool is executed, it first retrieves the byte offset of a key word from the index file, positions to the æKY line in the help file, and then reads all of the following lines until another æKY typed line is encountered. Get then outputs the record, after first removing the field tag codes from each field. Therefore, if the contents of a help file are altered in any way, it is necessary that the index be rebuilt. This is handled automatically by the Get tool, which puts up a dialog stating that the index needs to be rebuilt and requesting permission. In ordinary circumstances, this dialog should be answered affirmatively. About the files in your "411" folder The "411" folder contains the following files: :411: Install411 # the "411 installation script. CIncludesHelp # the CIncludesHelp data file. CIncludesHelp.index # the CIncludesHelp index file. CIncludesHelp.windex # the CIncludesHelp cross reference index file. InsideMacintoshHelp # Vols. 1-6 data file. InsideMacintoshHelp.index # Vols. 1-6 index file. InsideMacintoshHelp.windex # Vols. 1-6 cross reference index file. MPWHelp # the MPWHelp data file. MPWHelp.index # the MPWHelp index file. MPWHelp.windex # the MPWHelp cross reference index file. PInterfacesHelp # the PInterfacesHelp data file. PInterfacesHelp.index # the PInterfacesHelp index file. PInterfacesHelp.windex # the PInterfacesHelp cross reference file. ResourcesHelp # the ResourcesHelp data file. ResourcesHelp.index # the ResourcesHelp index file. ResourcesHelp.windex # the ResourcesHelp cross reference index file. TechNotesHelp # the TechNotesHelp data file. TechNotesHelp.index # the TechNotesHelp index file. TechNotesHelp.windex # the TechNotesHelp cross reference index file. :411:Tools: Get # the Get MPW tool - used to # look up help info. UserStartup•Help # the "411" UserStartup script. Files created by "411" The following files are created by the UserStartup•Help script, either at startup time, or as the result of execution of menu items created by the script. They all reside in the folder "{MPW}Help Folder:" Help # your "411" Help window. Help_Folder # contains the "411" path name # (path name to help data and # index files) Help_Files # contains the list of all help # files (full file names including path) Help_Temp # temporary file used by the "411" menu æKY AddPane æC AddPane-- split the window into panes AddPane[-p paneSpec] [-h ySplit | -v xSplit] [window] -p paneSpec # choose a pane to split -y ySplit # horizontal split at ySplit pixels from top -x xSplit # vertical split at xSplit pixels from left Note: paneSpec is an alternating catenation of strings of the form cm and rn, where m is a column ordinal and n is a row ordinal. æKY AddMenu æC AddMenu -- add a menu item AddMenu [menu [item [command…]]] > menuList Status codes returned: 0 No errors. 1 Syntax error. 2 An item can’t be redefined. 3 System error. Description Associates a list of commands with the menu item itemName in the menu menuName. If the menu menuName already exists, the new item is appended to the bottom of that menu. If the menu menuName doesn’t already exist, a new menu is appended to the menu bar, and the new item is appended to that menu. When the new menu item is selected, its associated command list is executed just as though the command text had been selected and executed in the active window. • Note: The command text that you specify for an AddMenu item is processed twice—once when you execute the AddMenu command itself, and again whenever you subsequently select the new menu item. This means that you must be careful to quote items so that they are processed at the proper time. See the "Examples" section below. You can also use AddMenu to display information for existing user-defined menus by omitting parameters: • If command is not specified, the command list associated with itemName is written to standard output. • If itemName and command are both omitted, a list of all user-defined items for menuName is written to standard output. • If no parameters are specified, a list of all user-defined items is written to standard output. (This output is in the form of AddMenu commands.) You can also use AddMenu to change the command list or markings associated with a particular itemName. If both menuName and itemName already exist, the command list associated with itemName will be changed to command. Also, any marking or styles associated with itemName will be changed. The position of itemName in menuName will not be affected. You can define keyboard equivalents, character styles, and other features for your new menu commands—itemName can contain any of the metacharacters that are used with the AppendMenu( ) procedure documented in the MPW chapter entitled "Menu Manager" of Inside Macintosh: /char Assign the keyboard equivalent Command-char. !char Place char to the left of the menu item. ^n Item has an icon, where n is the icon number. See Inside Macintosh. ( Item is disabled (dimmed). <style Item has a special character style; this style can be any of the following capital letters: B Bold I Italic U Underline O Outline S Shadow Multiple styles may be specified by preceding each with "<". Be sure to quote menu items containing these special characters. (See the "Examples" section below.) • Note: Semicolons ( ; ) cannot be used within an itemName. Menu items can’t be appended to the Window, Mark, or Apple menus. Examples AddMenu Lists all user-defined menu items. AddMenu Extras "TimeStamp//P" 'Echo `Date`' Adds an "Extras" menu with a "TimeStamp" item, which writes the current time and date to the active window. This item has the Command-key equivalent Command-P. AddMenu File 'Format<B' 'Erase 1' Adds a "Format" item to the File menu (as discussed under the Erase command) and makes the item bold. AddMenu Find Top 'Find • "{Active}"' Adds the menu item "Top" to the Find menu, and defines it as the Find command enclosed in single quotation marks. This command places the insertion point at the beginning of the active window. Note: The following attempt to do the same thing will not work: AddMenu Find Top "Find • {Active}" This command won’t work because the {Active} variable will be expanded when the menu is added. (It should be expanded when the menu item is executed.) In the first (correct) example, the single quotes defeat variable expansion when the AddMenu command is executed; they are then stripped before the item is actually added. The double quotation marks remain, in case the pathname of the active window happens to contain any special characters. You may want to add some or all of the following commands to your UserStartup file: AddMenu Find '(-' '' AddMenu Find 'Top/6' 'Find • "{Active}"' AddMenu Find 'Bottom/5' 'Find ∞ "{Active}"' These commands create several new items in the Find menu. The first is a disabled separator that creates a new section at the bottom of the menu. The Top and Bottom items position the insertion point at the top and bottom of the active window. Both menu items have Command-key equivalents. AddMenu Directory 'Work' 'Directory HD:MPW:Work' AddMenu Directory 'Work!•' 'Directory HD:MPW:Work' The first command creates a command to move to the directory HD:MPW:Work. The second command marks the Work item with a bullet without changing the position of the item in the menu. See also DeleteMenu command. "Quoting Special Characters," "How Commands Are Interpreted," and "Defining Your Own Menu Commands" in Chapter 5. "Creating a Menu in Your Program" in chapter "Menu Manager" of Inside Macintosh. æKY Adjust æC Adjust -- adjust lines Adjust [-c count] [-l spaces] selection [window] -c count # repeat the Adjust count times -l spaces # shift lines by "spaces" spaces Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Another error. Description Finds and selects the given selection and shifts all lines within the selection to the right by one tab, without changing the indentation. If a count is specified, count instances of selection are affected. The -l option lets you move lines by any number of spaces to the left or right. If you specify the window parameter, the command operates on window. It’s an error to specify a window that doesn’t exist. If no window is specified, the command operates on the target window (the second window from the front). Examples Adjust -l 4 § Shifts the lines containing the target selection to the right by four spaces. Adjust -l -8 /if/Δ:Δ/else/ Selects everything after the next "if" and before the following "else", and shifts all lines within the selection to the left by eight spaces. See also Align command. "Selections" in Chapter 6. æKY Alert æC Alert -- display an alert box Alert [-s] [message…] < file -s # silent, don't beep when dialog is displayed Status codes returned: 0 No errors. 1 Syntax error. Description Displays an alert box containing the prompt message. The alert is displayed until its OK button is clicked. If the message contains any special characters, you’ll need to quote it. Examples Alert Please insert next disk to be searched. Displays the following alert box and waits for the user to click "OK" before returning. Also see Confirm and Request commands. æKY Alias æC Alias -- define or write command aliases Alias [name [word…]] > aliasList Status codes returned: 0 No errors. 1 The specified alias could not be found. Description Name becomes an alias for the list of words. Subsequently, when name is used as a command name, word… will be substituted in its place. If only name is specified, any alias definition associated with name is written to standard output. If name and word are both omitted, a list of all aliases and their values is written to standard output. (This output is in the form of Alias commands.) Aliases are local to the script in which they are defined. An initial list of aliases is inherited from the enclosing script. Inherited aliases may be overridden locally. You can make an alias definition available to all scripts by placing the definition in the UserStartup file. You can remove aliases with the Unalias command. Examples Alias Dir Directory Creates an alias "Dir" for the Directory command. Alias Top 'Find •' Creates an alias "Top" for the command "Find •" (which places the insertion point at the beginning of a window). The command takes an optional window parameter and by default acts on the target window. The Top command could now be used as follows: Top # find top of target window Top Sample.a # find top of window Sample.a # (equivalent to "Find • Sample.a") See also Unalias command. "Command Aliases" in Chapter 5. æKY Align æC Align -- align text to left margin Align [-c count] selection [window] -c count # repeat the Align count times Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Any other error. Description All lines within each instance of the selection are positioned to the same distance from the left margin as the first line in the selection. If you specify the window parameter, the Align command will act on window. It’s an error to specify a window that doesn’t exist. If no window is specified, the command operates on the target window (the second window from the front). Examples Align § Same as the Align menu item; that is, it aligns all lines in the default selection with the first line of the selection. Align /Begin/:/End/ Selects everything from the next "Begin" through the following "End", and aligns all lines within the selection to the same margin position as the line that contains the "Begin". See Also Adjust command. "Selections" in Chapter 6. æKY Asm æC Asm -- MC68xxx Macro Assembler Asm [option…] [file…] < file > listing ≥ progress -addrsize size # set size of address display -blksize blocks # use blocks * 512 byte I/O buffers -case on # distinguish between upper and lower case -case obj[ect] # preserve case in object file -case off # ignore case (default) -c[heck] # syntax check only, don't create object file -d[efine] name # equivalent to: name EQU 1 -d[efine] name=value # equivalent to: name EQU value -d[efine] &name # equivalent to: &name SET[AC] 1 -d[efine] &name=value # equivalent to: &name SET[AC] value -e[rrlog] file # write errors and warnings to file -f # suppress page ejects in listing -font name[,size] # set listing font and size -h # suppress page headers in listing -i directory,… # search for includes in directory,… -l # write full listing to output -lo file # listing output file or directory -model far # allow generation of load-time relocatable 32-bit references -model near # prohibit generation of load-time relocatable 32-bit # references (the default) -o objname # generate code in file or directory objname -pagesize l[,w] # set listing page length and width -print mode # equivalent to: PRINT mode -p # write progress information to diagnostics -s # write short listing to output -sym off # no SADE records -sym on|full # full SADE records; can modify with [,nolines] # [,notypes] [,novars] -t # write time and total lines to diagnostics -w # suppress warnings -wb # suppress warnings on branch instructions Status codes returned: 0 No errors detected in any of the files assembled. 1 Parameter or option errors. 2 Errors detected. Description Assembles the specified assembly-language source files. One or more filenames may be specified. If no filenames are specified, standard input is assembled and the file "a.o" is created. By convention, assembly-language source filenames end in the suffix ".a". Each file is assembled separately—assembling file name.a creates object file name.a.o. The object filename can be changed with the -o option. See the MPW 3.0 Assembler Reference for more information about the assembly language. The first Commando dialog box for this command is reproduced here for convenience. Examples Asm -w -l Sample.a Memory.a -d Debug Assembles Sample.a and Memory.a, producing object files Sample.a.o and Memory.a.o. Suppresses warnings and defines the name Debug as having the value 1. Two listing files are generated: Sample.a.lst and Memory.a.lst. (Sample.a and Memory.a are located in the AExamples directory.) See Also MPW3.0 Assembler Reference. æKY Backup æC Backup -- folder file backup Backup [option…] -from folder -to folder [file…] > commands ≥ progress -a # copy all files in "from" not in "to" -alt # alternate prompts for disk drives -c # create "to" folders if they don't exist -check checkopt,… # produce reports based on checkopt # checkopt=from "from" not in "to" # to "to" not in "from" # allfroms "from" not in "to" even if none # alltos "to" not in "from" even if none # folders "from" folders not in "to" # newer "to"s newer than "from"s -co filename # redirect -check reports to filename -compare [only][,'opts']# write compare commands for out-of-date files -d # write delete commands for files in "to" not in "from" -do [only][,'command'] # write the command string specified by command… -e # eject disk when done -from folder|drive # specify source folder or drive (1 or 2) -l # write directory listing of "from" files -lastcmd 'command' # write the command string as the last command -level n # restrict -a and -d to files beyond level n -m # multi-disk -- more than one "from" or "to" disk -n # show folder nesting by indenting commands -p # write progress information to diagnostics -r # recursively process nested folders -revert # revert "to" files to their "from" state -since date[,time]|fname# process only files since specified time -sync # synchronize both source and destination folders -t type # process only files of specified type -to folder|drive # specify destination folder or drive (1 or 2) -y # suppress duplicate -y option Status codes returned: 0 No errors; Shell duplicate commands have been generated or filenames were listed. 1 Parameter or option errors. 3 No errors and no files to duplicate or list. Note: Backup returns a status code of 3 when no files need copying. If no files are copied because none of the files in the source folder exists in the destination folder, Backup also reports a warning to the diagnostic output file. If there are no name matches, it is possible that your from/to pathnames were specified incorrectly. Hence, Backup lets you know of the possible error. Backup does not report this as an error if you use the -l, -a, or -since option. Description Files in a source ("from") folder are copied to a destination ("to") folder based on the modification date. By default, only files that already exist in both the source and destination folders are candidates for copying. (The -a option can override this default.) Backup does not actually make the copies. Instead, it generates a script of MPW Shell duplicate commands. Backup’s default operation is based on the premise that you already have an existing folder on two sets of disks (generally a hard disk and a set of 3.5-inch disks—drive numbers may be specified as folder "names") and that you want to make sure that the files on one of the disks are the same as the files on the other disk. Thus, it is the files on the destination ("to") disk that determine which files can be copied from the source ("from") disk. A Shell duplicate command is generated to the standard output file if • a file on a source disk also exists on the destination disk, and • the modification date of the source is newer than that of the destination. In addition to the basic function of generating Shell duplicate commands, Backup also provides these services: • Folders can be recursively processed, allowing processing of all folders and subfolders contained within folders (-r). • Compare commands can be generated for out-of-date files of type TEXT to discover why the files are different (-compare). • Filenames that exist on one disk and not on the other can be displayed (-check from,to). • File folder names that don’t exist on the destination can be displayed (-check folders). • Filenames in the destination that are newer than the source can be displayed (-check newer). Examples backup -from :HDfolder: -e Check that all files on the disk in drive 1 (-to is omitted, so "-to 1" is implied) are up to date with respect to the files in :HDfolder:. If they are, the disk in drive 1 is ejected. If not, the appropriate Duplicate commands are generated to update the out-of-date files on the disk in drive 1. An Eject 1 command is generated to eject the disk after the Duplicate commands are processed. backup -r -from FServer:MPW: -to HD:MPW: -check folders Recursively process (-r) all the files in all the folders on FServer:MPW: to make sure that the files on HD:MPW: are up-to-date. Appropriate Duplicate commands are generated to copy the out-of-date files from the folders in FServer:MPW: to the folders in HD:MPW:. It is assumed that the folder names in HD:MPW: are the same as the folder names in FServer:MPW:. Any folders in FServer:MPW: that don’t exist in HD:MPW are skipped. Because the -check option is specified, a list of all the skipped folders is written to the diagnostic file. Limitations Multi-disk operation (-m) is not supported with recursion (-r). The -e option is ignored when -m is specified. Only drive numbers 1 and 2 are supported, and they are assumed to be ejectable 3.5-inch disk drives. æKY Beep æC Beep -- generate tones Beep [note [,duration [,level]]]… # duration is given in sixtieths of a second (default is 15) # sound level is given as a number from 0 to 255 (default is 128) Status code returned: 0 no errors. Description For each parameter, Beep produces the given note for the specified duration and sound level on the Macintosh speaker. If no parameters are given, a simple beep is produced. Note is one of the following: • A number indicating the count field for the square wave generator, as described in chapter "Summary of the Sound Driver" of Inside Macintosh. • A string in the following format: [ n ] letter [ # | b ] n is an optional number between –3 and 3 indicating the octaves below or above middle C, followed by a letter indicating the note (A–G) and an optional sharp (#) or flat (b) sign. Note that any sharps (#) must be enclosed in quotation marks—otherwise they will be interpreted as comment delimiters. The optional duration is given in sixtieths of a second. The default duration is 15 (one-quarter second). The optional sound level is given as a number from 0 to 255. The default level is 128. Examples Beep Produce a simple beep on the speaker. Beep 2C,20 '2C#,40' 2D,60 Play the three notes specified: C , C sharp, and D—all two octaves above middle C—for one-third, two-thirds, and one full second, respectively. Notice that the second parameter must be quoted; otherwise the sharp character (#) would indicate a comment. æKY Begin æC Begin -- group commands Begin command… End The status code of the last command executed is returned. (If no commands appear between Begin and End, 0 is returned.) Description Groups commands for pipe specifications, conditional execution, and input/output specifications. Carriage returns must appear at the end of each line as shown above, or be replaced with semicolons ( ; ). If the pipe symbol (|), conditional execution operators (&& and ||), or input/output specifications (<, >, >>, ≥, ≥≥, ∑, ∑∑) are used, the operator must appear after the End command and applies to all of the enclosed commands. • Note: Begin and End behave like left and right parentheses. Once the Begin command has been executed, the Shell will not execute any of the subsequent commands until it encounters the End command, so that input/output specifications can be processed. Examples The following commands save the current variables, exports, aliases, and menus in the file SavedState. Begin Set Export Alias AddMenu End > SavedState Notice that the output specification following "End" applies to all of the commands within the Begin…End control command. This command is identical to the following: (Set; Export; Alias; AddMenu) > SavedState The commands Set, Export, Alias, and AddMenu write their output in the form of commands; these commands can be executed to redefine variables, exports, aliases, and menus, respectively. Therefore, after executing the above commands, the command Execute SavedState will restore all of these definitions. You must "execute" the script so that the variables and aliases are applied to the current scope. • Note: This technique is used in the Suspend script to save state information. (You might want to take a look at Suspend, which also saves the list of open windows and the current directory.) The Resume file runs the file that Suspend creates, restoring the various definitions, reopening the windows, and resetting the current directory. æKY Break æC Break -- break from For or Loop Break [If expression] Status codes returned: 0 No errors detected. –3 Break is found outside a For…End or Loop…End, or the parameters to Break are incorrect. –5 Invalid expression. Description If expression is nonzero, Break terminates execution of the immediately enclosing For or Loop command. (Null strings are considered zero.) If the "If expression" is omitted, the break is unconditional. (For a definition of expression, see the Evaluate command.) Examples Set Exit 0 For file in Startup UserStartup Suspend Resume Quit EnTab "{file}" > temp Break If {Status} != 0 Rename -y temp "{file}" Print -h "{file}" Echo "{file}" End This For loop entabs and prints each of the special MPW scripts; the Break command terminates the loop if a nonzero status value is returned. (See the For command for further explanation of this example.) Set loopcount | Loop Break if {loopcount} > 10 Echo "Loop Number {loopcount}" Evaluate loopcount +=1 End This example loops until the variable {loopcount} is greater than 10. Use of the Evaluate command is also demonstrated. See also For, Loop, and If commands. Evaluate command (for a description of expressions). "Structured Commands" in Chapter 5. æKY Browser æC Browser -- invoke Marker Browser # The MPW Browser command is used to navigate source files or other text. It # presents a window containing a list of the files in the current directory # and, for the selected file, a list of markers. Double-clicking on the marker # opens the file with the selection point at the marker. Entering a marker name # in a text box searches all files in the directory for that marker, and if found # opens the file with the selection point at the marker. æKY BuildCommands æC BuildCommands -- show build commands BuildCommands program [option…] > commands option… # Make command options Status code 0 is returned if the build commands are generated without error. If an error occurs, the status code returned by Make is returned. Description BuildCommands writes to standard output the commands needed to build the specified program. Make is used to generate the build commands. If file program.make exists, it is used as the makefile. If not, file MakeFile is used. The specified options control the generation of the build commands. The options are passed directly to Make. BuildCommands is used to implement the Show Build Commands and Show Full Build Commands menu items in the Build Menu. Examples Open {Worksheet} BuildCommands Count >> {Worksheet} ≥≥ Dev:StdOut Generates the build commands for Count. The Worksheet window is brought to the front. The build commands, or any errors generated by Make are written at the end of the Worksheet. The Show BuildCommands menu item is implemented using similar commands. See also "Building a Program: An Introduction" in Chapter 2 æKY BuildMenu æC BuildMenu -- create the Build menu Status codes returned: 0 is always returned. Description Creates the Build menu shown below. Each of the items in the menu is described in Chapter 3 of the MPW Manual. Examples BuildMenu Creates the Build menu. This command should appear in the UserStartup file to create the Build menu. See also "Building a Program: An Introduction" in Chapter 2. æKY BuildProgram æC BuildProgram -- build the specified program Status code 0 is returned if the build is completed without error. If an error occurs during the generation of the build commands, the status value returned by Make is returned. If an error occurs during the build, the Status value returned by the build step that detected the error (such as Asm or Link) is returned. BuildProgram program [option…] > log option… # Make command options Description Builds the specified program. A simple transcript of the build, including timing information and commands used to do the build, is written to standard output. Make is used to determine the commands needed to do the build. If file program.make exists, it is used as the makefile. If not, the file MakeFile is used. The options specified are passed directly to Make; they control the generation of the build commands. BuildProgram is used to implement the Build and Full Build menu items in the Build menu. Examples Open {Worksheet} BuildProgram -e Count >> {Worksheet} ≥≥ Dev:StdOut Completely rebuilds Count. The Worksheet window is brought to the front. The transcript of the build and any errors are written at the end of the Worksheet. The Full Build menu command is implemented using similiar commands. See also "Building a Program: An Introduction" in Chapter 2 æKY C æC C -- C compiler C [option…] [file] < file > preprocessor ≥ progress -b # put string constants into code and generate PC-relative references # for function addresses -b2 # implies '-b' above, and allows string constants to be overlaid -b3 # overlaid string constants in code (but A5-relative references # for function addresses) -bigseg # generate single large (>32K) code segment, 68020 only -c # syntax check only, don't create object file -d name # equivalent to: #define name 1 -d name=string # equivalent to: #define name string -e # write preprocessor results to output -e2 # implies '-e' above, and strips comments -elems881 # generate MC68881 code for transcendentals -i directory # search for includes in directory -k directory # create load/dump files in directory -m # generate 32-bit references for data (less efficient code) -mbg ch8 # v2.0 compatible macsbug symbols -mbg off # no macsbug symbols in the code -mbg on|full # full macsbug symbols -mbg <n> # macsbug symbols to length <n> (<n> can be 0..255) -mc68020 # generate MC68020 code -mc68881 # generate MC68881 code for arithmetic operations -model farCode| # generate load-time relocatable 32-bit references for farData|far # code, data, or both -model nearCode| # generate 16-bit references for code, data, or both nearData|near # (the default) -n # Turn pointer assignment incompatibility errors into warnings -notonce # do not automatically suppress multiple inclusion of files -o objname # generate code in file or directory objname -opt off # don't apply code optimizations -opt on | full # choose level of code optimization ( on is default ); # can modify with [,nopeep] [,nocse] # ( no peephole, no common subexpression) -p # write progress information to diagnostic -r # warn on calling a function that has no definition -s segment # generate code in segment -sym off # don't generate SADE records -sym on | full # generate SADE records; can modify with [,nolines] [,notypes] [,novars] -t # write compilation time to diagnostic -trace always|never # enable/disable calls to profiler or MacApp debugger # (overrides #pragma trace on|off) -trace on|off # enable/disable calls to profiler or MacApp debugger # (subject to #pragma trace on|off) -u name # equivalent to: #undef name -warnings on|off|full # set warning level; "on" is the default -y directory # create temporary files in directory Status codes returned: 0 Successful completion. 1 Errors occurred. Description Compiles the specified C source file. Compiling file Name.c creates object file Name.c.o. (By convention, C source filenames end in a ".c" suffix.) If no filenames are specified, standard input is compiled and the object file "c.o" is created. (Note that SADE object file information cannot be generated for standard input source files.) See the MPW 3.0 C Reference Manual for details of the C language definition. Examples C -p Sample.c Compiles Sample.c, producing the object file Sample.c.o. Writes progress information to diagnostic output. (Sample.c is found in Examples:CExamples.) See also MPW3.0C Reference. æKY Canon æC Canon -- canonical spelling tool Canon [option…] dictionary [file…] < file > new -s # case sensitive replacement -a # assembler identifiers (include $, %, @) -c n # consider only the first n characters Status codes returned: 0 All files processed successfully. 1 Error in command line. 2 Other errors. Description Canon copies the specified files to standard output, replacing identifiers with the canonical spellings given in dictionaryFile. If no files are specified, standard input is processed. DictionaryFile is a text file that specifies the identifiers to be replaced and their new (or canonical) spellings. Identifiers are defined as a letter followed by any number of letters or digits. (The underscore character ( _ ) is also considered a letter.) Each line in the dictionary contains either a pair of identifiers or a single identifier: • If two identifiers appear, the first is the identifier to replace, and the second is its canonical spelling. For example, the dictionary entry NIL NULL # change NIL to NULL changes each occurrence of "NIL" to "NULL". • A single identifier specifies both the identifier to match and its canonical spelling. This feature is useful because the matching may not be case sensitive or restricted to a fixed number of characters. (See the "Options" section on the next page.) For example, the dictionary entry true changes all occurrences of "TRUE", "True", "tRUE", and so on to "true". You can specify a left context for the first identifier on each line of the dictionary by preceding it with a sequence of nonidentifier characters. Replacement will then occur only if the left context in the input file exactly matches the left context in the dictionary. For example, if C structure component upperLeft should be replaced with topLeft, the dictionary might include the following: .upperLeft topLeft ->upperLeft topLeft You can include comments in the dictionary file by using the # symbol: everything from the # to the end of the line is ignored. • Note: The file Canon.Dict is a sample dictionary file that’s included with MPW. (See the "Examples" section below.) Examples The file Canon.Dict, in the Tools folder, contains a list of all of the identifiers used in the Standard C library and the Inside Macintosh C interfaces. This list was made from the Library Index in the MPW 2.0 C Reference. The entries in Canon.Dict look like the following: abbrevDate ABCallType abortErr ABProtoType abs acos activateEvt … The following command copies the file Source.c to the file Temp; identifiers whose first eight characters match a dictionary entry are replaced with that entry. Canon -c 8 {MPW}Tools:Canon.Dict Source.c > Temp The -c 8 option is useful when porting source code from other systems where only eight characters are significant. • Note: The list of Pascal identifiers used in the Inside Macintosh interface is almost identical to the list used in C. The dictionary Canon.Dict can also be used to port Pascal programs from other systems, as long as you use the canonical capitalizations for the various Standard C library identifiers. Limitations The maximum line length in the dictionary file is 256 characters. Longer lines are considered an error. Identifiers and words in comment sections are replaced. æKY Catenate æC Catenate -- concatenate files Catenate [file…] < file > catenation Status codes returned: 0 All files were processed successfully. 1 One or more files were not found. 2 An error occurred in reading or writing. Description Catenate reads the data fork of each file in sequence and writes it to standard output. If no input file is given, Catenate reads from standard input. None of the input files may be the same as the output file. Examples Catenate Makefile.a Writes Makefile.a to the active window immediately following the command. Catenate File1 File2 > CombinedFile Concatenates the first two files and places the result in the third. If CombinedFile doesn’t exist, it will be created; if it exists, it will be overwritten. Set selection "`Catenate §`" Captures the selection from the target window in the Shell variable {selection}. Catenate >> {Worksheet} Appends all subsequently entered text to the Worksheet window (until you indicate end-of-file by pressing Command-Enter). Warning Beware of commands such as Catenate File1 File2 > File1 The above command will cause the original data in File1 to be lost. To append one file to another, use the form Catenate File2 >> File1 See also Duplicate command. "Redirecting Input and Output" in Chapter 5. æKY CFront æC CFront -- C++ to C translator CFront [option…] [file…] < file > intermediate output ≥ progress -a # force ANSI-style intermediate C code (default) -a0 # force K&R-style (pre-ANSI) intermediate C code -a1 # force ANSI-style intermediate C code (default) -c # intermediate code to standard output; no object file -d name # equivalent to: #define name 1 -d name=string # equivalent to: #define name string -e # write preprocessor results to output -e2 # implies '-e' above, and strips comments -elems881 # generate MC68881 code for transcendentals -f filename # act as if input comes from named file when it actually is from stdin -f1 # send text version of C code to C compiler (no token stream) -i directory # search for includes in directory -mc68020 # generate MC68020 code -mc68881 # generate MC68881 code for arithmetic operations -mtbl0 # suppress output of method tables for Object Pascal Classes -mtbl1 # force output of method tables for Object Pascal Classes -n # Turn pointer assignment incompatibilty errors into warnings -p # write progress information to diagnostic -s segment # generate code in segment -u name # equivalent to: #undef name -vtbl0 # suppress output of virtual tables for ordinary class -vtbl1 # force output of virtual tables for ordinary class -vtbl2 # new improved output algorithm for virtual tables -w # suppress warnings -w1 # generate additional warnings from CFront -w3 # passed through to C compiler (supresses unused warnings) -y directory # create temporary files in directory -z0 # force 'inline' functions to be non-inline -z3 # supress name encoding of local vars and struct members (default) -z4 # encode names of local vars and struct members -z6 # force enums always to be int variables -z7 # relax requirement on static class member initialization æKY CheckIn æC CheckIn -- check a file into a project CheckIn -w | -close | ([options…] files…) > progress -a # checkin all files in current directory -b # check in files… as branches -c # cancel if conflict occurs (avoids dialog) -cf file # the comment is contained in file. -close # close the Check In window -cs comment # a description of changes made to the file -delete # delete the file after checking it in -m # check out the files for modification after checking in -n # answer no to all dialogs (avoids dialogs) -new # add a new file to the project -p # write progress information to standard output -project project # name of project that contains the files -t task # a short description of task accomplished -touch # touch the mod date of file after checking in -u user # name of current user -w # open the Check In window -y # answer yes to all dialogs (avoids dialogs) Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Return ownership of the specified files to Projector and save all changes as new revisions. The default is to leave you with a read-only copy of the file. File must be an HFS pathname. Projector determines the project each file belongs to by inspecting the file's resource fork. Since Projector puts the name of the project in the resource fork of checked-out files, files belonging to different projects can be checked in with a single command. If the -a (all) option is used instead of file..., Projector examines all files in the current directory and checks in all files in the current directory that have been checked out for modification. The files are checked into their respective projects. To add a new file to the project, use the -new option. When the file is checked in, Projector automatically increments the revision number by one. For example, if revision 2.17 was checked out, the new revision will be 2.18. To override this, use the ProjectInfo command to find the revision number, increase it by the amount desired, and then check the file in, using the "filename,rev" notation. For example, if file.c revision 2.17 was checked out, you could check it in as file.c,3.0 to jump to the next major revision level. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples CheckIn file.c -cs "added some comments" Check in file.c to the current project. A new revision of file.c is created and the user is left with a read-only copy of the file. The comment is saved with the new revision. Because no revision number is specified, Projector simply increases the revision number by one. CheckIn file.c interface.c,5 -t "Added -x option" -cf commentFile This command checks in two files reading the comment from the file commentFile. The task is also saved with the new revisions. The user is left with read-only copies of the files. The new revision for interface.c is revision 5. CheckIn hd:work:file.c hd:work:main.c -m The files to be checked in are hd:work:file.c and :main.c. After the command executes, the user still has modifiable copies of the files. CheckIn -new file.c To check a new file into the project use the -new option. The above command adds file.c to the current project. CheckOut -project Zoom∫Utilities∫MyProject file.c -m ...edit the file... CheckIn -project Zoom∫Utilities∫MyProject file.c -b The preceding command sequence illustrates the usefulness of the -b option. In this case, the user checked out a write-privileged copy of the latest revision of file.c from the current project, edited the file, and then, using the branch option, checked in the file on a branch. See also CheckOut and CheckOutDir. æKY CheckOut æC CheckOut -- check a file out from a project CheckOut -w | -close | ([options…] files…) > progress -a # check out all the files in the current project -b # checkout specified files on a new branch -c # cancel if conflict occurs (avoids dialog) -cancel # cancel the checkout of the files -cf file # the comment is contained in files -close # close the Check Out window -cs comment # a short description of changes -d dir # directory where the checked out files should go -m # check out a modifiable copy of the file -n # answer no to all dialogs (avoids dialogs) -newer # checkout latest copy of all files in the project -noTouch # don't touch the mod date of the checked out files -open # open the files after checking out -p # write progress information to standard output -project project # name of project that contains the files -r # recursively checkout files -t task # a short description of task accomplished -u user # name of current user -update # checkout latest copy of all files you already have -w # open the Check Out window -y # answer yes to all dialogs (avoids dialogs) Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Under Projector, CheckOut obtains copies of file revisions from a project. The default is to check out read-only copies. Unless otherwise specified, copies are placed in the checkout directory associated with the project. If file is a leafname (that is, file.c), Projector checks out the latest revision of the file from the current project. If file specifies a revision (for example, file.c,22), that revision is checked out. If file is a partial or full HFS pathname (that is, :work:file.c or HD:work:file.c), the file does not go into the checkout directory. Instead, Projector checks out the file (that is, file.c) in the current project and places the copy in the specified HFS location (that is, in the :work: or HD:work: directory, respectively). Finally, file may be a Name. See the NameRevisions command for more information about Names. The Name is expanded and the corresponding revisions are checked out. To check out an old revision for modification, you must specify the -b (branch) option. If you are checking out revision 5 of file.c into hd:work and Projector determines that you already have that revision in the work directory, Projector will not recopy the data of revision 5. This is especially nice when you are checking out a revision for modification, and you already have a read-only copy of that revision. See Chapter 7 of MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples CheckOut -m -project Zoom∫Utilities∫MyProject file.c Checks out a write-privileged copy of the latest revision of file.c from the Zoom∫Utilities∫MyProject project. The file is placed in the checkout directory for the project. CheckOut -m file.c The above command checks out the latest revision of file.c for modification. The file is placed in the checkout directory for the project. If you already happen to have the latest revision of file.c in the checkout directory, then Projector only updates the 'ckid' resource of file.c to indicate that it is now a modifiable file. CheckOut -project Zoom∫Utilities∫Kerfroodi file.c,22 The above command checks out a read-only copy of revision 22 of file.c from the Zoom∫Utilities∫Kerfroodi project. The file is placed in the checkout directory for the project. Project Zoom∫Utilities∫Kerfroodi CheckOut file.c -t "Fix Bug 7" -m -d "{Zoom}UtilitiesSrc:Kerfroodi" By setting the current project with the Project command you don’t need to specify a project on subsequent Projector commands. By setting the task other users will be able to see why you have checked out file.c. The files are placed in {Zoom}UtilitiesSrc:Kerfroodi. CheckOut -a -d HD:Work:Test The above example checks out read-only copies of all of the files in the current project and places the copies in the directory HD:work:Test. CheckOut -a -project Zoom∫ -r Checks out read-only copies of all files in the Zoom project and all of its subprojects. Its behavior is the same as if you had executed these commands individually: CheckOut -a -project Zoom∫ CheckOut -a -project Zoom∫Voom CheckOut -a -project Zoom∫Utilities CheckOut -a -project Zoom∫Utilities∫MyProject ... You can conveniently update the read-only files (from the current project) in the current directory without affecting any files checked out for modification. To do this, use the -update option: CheckOut -update -d : See also CheckIn and CheckOutDir. æKY CheckOutDir æC CheckOutDir -- specify the directory where checked out files will placed CheckOutDir [-project project | -m] [-r] [-x | directory] -project project # name of project to associate with the checkout directory -m # list the checkout directories of all root projects -r # recursively set or display the checkout directories -x # reset the checkout directories to ":" Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Under Projector, CheckOutDir changes the checkout directory associated with the current project to the HFS pathname directory. From this point on, files checked out of the named project are placed, by default, into this directory. The directory is created if it does not exist. When a project is mounted, the checkout directory is initially set to ":"—that is, the current directory. It is recommended that you put CheckOutDir commands immediately following the corresponding MountProject commands you place in your UserStartup file, script, or AddMenu for project initialization. If directory is missing, the checkout directory of the current project is written to standard output in the form of a CheckOutDir command. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples CheckOutDir HD:work:Test This command causes subsequent files in the current project to be checked out to the HD:work:Test folder. CheckOutDir CheckOutDir -project Zoom∫Utilities∫Test HD:work:Test The above command outputs the checkout directory of the current project in the form of a CheckOutDir command. CheckOutDir -project Zoom∫ -r CheckOutDir -project Zoom∫ : CheckOutDir -project Zoom∫Vroom : CheckOutDir -project Zoom∫Utilities : CheckOutDir -project Zoom∫Utilities∫Test HD:work:Test The -r option lets you display the checkout directory for the current project and all subprojects. In this case, only the sort project has a checkout directory setting that differs from the default. The -r option can also be used to set the checkout directories of a complex project to mirror the projects own hierarchical structure. For example: CheckOutDir -project Zoom∫ -r HD:Work: After executing the above command, listing the checkout directories for the projects under Zoom yields CheckOutDir -project Zoom∫ -r CheckOutDir -project Zoom∫ HD:work: CheckOutDir -project Zoom∫Vroom HD:Work:Vroom CheckOutDir -project Zoom∫Utilities HD:Work:Utilities CheckOutDir -project Zoom∫Utilities∫Test HD:Work:Utilities:Test Notice how the directory structure is similar to the project structure. The directories are created if they do not exist. The -m option lists the checkout directories of the root projects. For example CheckOutDir -m CheckOutDir -project Zoom∫ HD:Work:Zoom CheckOutDir -project Test∫ HD:Test See also MountProject, CheckIn, and CheckOut. æKY Choose æC Choose -- choose or list network file server volumes and printers Choose [option…] [[zone]:server[:volume] …] -askpw # ask for server password (in a "safe" dialog box) -askvp # ask for volume password (in a "safe" dialog box) -c # output in the form of further "Choose" commands. -cp # print driver name and type of current printer. -dr driverFileName # name of printer driver file in system folder # (e.g. "LaserWriter") -guest # log-in to the file server as a guest. -list # list entities (don't choose them). -p # print version information. -pr # choose printers (instead of file servers). -pw password # specify server log-in password. -u username # specify user name for server log-in. -v # verbose (print names of volumes really mounted). -vp volumePassword # specify volume password (to mount it). -type type # specify type of entity to list or choose (or '≈'). Names take the form "zone:server:volume" The wildcard '≈' may be used in place of a zone, server, volume or type name. A leading ':' (empty zone name) or '*:' indicates the current zone. A name of the form "…server:" will mount all volumes on the server, unless a specific volume name is given. Status codes returned: 0 No errors. 1 Syntax error on command line. 3 Any other error. Description Choose noninteractively mounts or lists the specified AppleShare volumes or printers. Each name takes the form [zone]:[server[:volume]] ("Server" means any file or printer server.) The zone name is always optional and defaults to the current zone. A server name must be preceded by (at least) a colon. Volume names are only applicable to file servers. When mounting file server volumes, a server name is required. If a volume name is specified, only that volume is mounted. If the volume name is omitted, or if it is the wildcard character "≈", all volumes on the server are mounted: [zone]:server:volume [zone]:server[:≈] When -list is specified, the wildcard character "≈" may be used in place of names in all of the fields: "≈" in the zone field expands to all zones; "≈" in the server field expands to all servers in the specified zones; "≈" in the volume-name field expands to volumes on the specified servers (listing volumes on a server requires a server login—that is, as a user with a valid password or as a guest). If the wildcard character "≈" is used, it must be quoted so that the Shell will not expand it. The -list option also expands the next unspecified item in a name. A zone name followed by nothing else expands to a list of servers in that zone, and a server name followed by nothing else expands to a list of volumes on the server. If a "≈", ":" or "" character appears in a server, volume, or zone name, it may be quoted with the character "". This quoting mechanism supplements quoting already performed by the Shell. Any number of volumes may be mounted (though a system-dependent limit exists on the number of active server connections). Only one printer may be chosen at a time, since only one printer can be active. Server and volume passwords are case sensitive. More than one server and volume may be mounted with a single command, but the server and volume passwords must be the same for each, since at most one password of each type may be specified on the command line. Examples Choose :Linker:Sources Mount the volume Sources on the server Linker, located in the current zone, using the default user name, server password, and volume password. Choose -v -guest 'Systems:Sources:Doc' 'Systems:Games:≈' Mount the volume Doc on the server Sources and every volume on the server Games in the zone Systems as a guest. Print the names of the volumes that are mounted by the command. List the names of all zones. Notice that the wildcard character "≈" is quoted. Choose -list 'Whale Zone:≈' 'Whale Zone:Moby Dick:≈' '≈:' List all file servers in the zone Whale Zone, all volumes on the file server Moby Dick in that zone (after logging in with the default user name and server password) and all zones (with their servers). Choose -pr -list ':≈' Choose -cp -pr Zarf:Kitchen Sink List all printers of the current type in the current zone. Print the name of the currently selected printer, then select the printer called Kitchen Sink in the zone Zarf. Choose -list -type Fortune Cookie Server '≈:≈' List all network entities of type Fortune Cookie Server in all zones. See also Unmount and Volumes commands. æKY Clear æC Clear -- clear the selection Clear [-c count] selection [window] -c count # repeat the Clear count times Status codes returned: 0 At least one instance of selection was found. 1 Syntax error. 2 Any other errors. Description Finds selection and deletes its contents. The selection is not copied to the Clipboard. (For a definition of selection, see Chapter 6 of the MPW manual.) If window is specified, the Clear command acts on that window. It’s an error to specify a window that doesn’t exist. If no window is specified, the command operates on the target window (the second window from the front). Examples Clear § Deletes the current selection. This is like the Clear command in the menu bar, except that the action occurs in the target window rather than the active window. Clear /BEGIN/:/END/ Selects everything from the next BEGIN through the following END, and deletes the selection. See also Cut and Replace commands. "Selections" in Chapter 6 (see Appendix B for a summary). æKY Close æC Close -- close specified windows Close [-y | -n | -c] [ -a | window…] -y # save modified windows before closing (avoids dialog) -n # don't save any modified windows (avoids dialog) -c # cancel if there is a modified window (avoids dialog) -a # close all the windows Status codes returned: 0 No errors. 1 Syntax error 2 Any other error, such as "Window not found." 4 Cancelled from dialog. Description Close the window or windows specified by window. If no window is specified, the target window is closed. If changes to the window have not been saved, a dialog box requests confirmation of the Close command. In scripts you can use the -y, -n, or -c option to avoid this interaction. Use the -a option instead of window to close all of the open windows (other than the Worksheet). Examples Close Closes the target window, prompting the user with a confirmation dialog box if needed. Close -a -y Saves and closes all open windows. Close -n Test.a Test.r Closes the windows Test.a and Test.r without saving any of the changes. See also "File Menu" in Chapter 3. æKY CMarker æC CMarker -- generate Mark commands for C and C++ function definitions CMarker [option…] [file…] -a[nachronisms] # suppress anachronisms messages -d[efine] name[=string] # define name to the preprocessor (same as #define) [,name[=string]]… -e # show macro expansion in the listing (default with -ppout) -ext[ensions] on|off # turn on or off Apple compiler extensions (default on) -errors # suppress marking if errors are detected -i[ncludes] pathname # search for include files in the specified directories (Max of 15) [,pathname],… -lang[uage] C|"C++" # specify target sources as either C or C++ (Default is C) -linesize n # maximum number of characters generated in a single listing line -l[ist[ing]] # generate a listing of the source to stdout -mc68881 # define the macro name mc68881 as having the value 1 -msi # mark include (header) files -pp # preprocessing only (no markers will be generated) -ppout filename # write the preprocessor output to the specified filename -p[rogress] # write version, progress and summary information to stderr -showskipped # show lines skipped by conditional compilation in the listing output -t # display processing time and number of lines to stderr -u[ndefine] name # undefine the preprocessor symbol name (same as #undef) [,name]… Status codes returned: 0 No errors. 1 Parameter or option error. 2 Execution error. 3 Syntax errors. Description CMarker reads the specified C++/ANSI C source file(s), syntax checks them and generates appropriate "Open" and "Mark" MPW commands, which, when executed, will mark the source file(s) at each function definition with the marker name being the name of the function. It's purpose is to aid in the marking of source files for use with the MPW "marker browser" capability. CMarker contains a full ANSI C preprocessor and provides options to mark include files, generate source listings (with or without showing macro expansions), run the preprocessor only, flag anachronisms, and syntax check C++/ANSI C with or without Apple extensions. CMarker runs as an MPW Tool. æKY Commando æC Commando -- present a dialog interface for commands Commando [command] [-modify] -modify # enable Commando’s built-in editor Status codes returned: 0 The Do It button was selected. 1 The Cancel button was selected. 2 Error occurred while parsing the cmdo resource. 3 I/O or program error. Description The Commando interface lets you operate any properly configured MPW tool or script using specialized Macintosh dialog boxes instead of the ordinary command line method. The dialogs make it easy to find options and build up complex command lines. Commands with many options and parameters may employ one or more nested dialog boxes. See "Commando Dialogs" in Chapter 4 of the MPW manual for more information on the basics of using the Commando dialogs. Chapter 13 describes the structure of the Commando resource and shows how to create Commando dialogs for your own tools and scripts. The controls of a Commando dialog box, including text fields, buttons, titles, and so on, can be sized and moved within the dialog box by using the mouse, exactly as you would drag an object in the Finder. See "Editing Commando Dialogs" in Chapter 13 for information on moving and sizing controls. Examples Commando Rez Displays the frontmost Rez dialog box shown under "Rez" in Part II. Rez… Displays the frontmost Rez dialog box shown under "Rez" in Part II, exactly as in the previous example. See also "Invoking Commando" in Chapter 4. Chapter 13. æKY Compare æC Compare -- compare text files Compare [option…] file1 [file2] < file2 > differences ≥ progress -b # treat several blanks or tabs as a single blank -c c1-c2[,c1-c2] # compare only specified columns -d depth # maximum stack depth -e context # display specified number of context lines -g groupingFactor # grouping factor (matching lines for resync) -h width # write differences horizontally -l # lower case (i.e. ignore case differences) -m # suppress displays of mismatched lines -n # don't write to output if files match -p # write progress information to diagnostics -s # use static grouping factor -t # ignore trailing blanks -v # suppress line numbers in vertical displays -x # don't expand tabs Status codes returned: 0 Files match. 1 Parameter or option error. 2 Files don’t match. Description Compares the lines of two text files and writes their differences to standard output. Options are provided to compare a specific column range in each file (-c), to ignore blanks (-b), and to ignore case (-l). Both files are read and compared line for line. As soon as a mismatch is found, the two mismatched lines are stored in two stacks, one for each file. Lines are then read alternately (starting from the next input line in file2 ) until a match is found to put the files back in synchronization. If such a match is found, Compare writes the mismatched lines to standard output. Files are considered resynchronized when a certain number of lines in the two stacks exactly match. By default, the number of lines, called the grouping factor, is defined by the formula G = Trunc((2.0 * Log10(M)) + 2.0) where G is the grouping factor and M is the number of lines saved in each stack so far. This definition requires more lines to be the same after larger mismatches. Using this formula, the following table shows the grouping factor G as a function of the number of mismatched lines: M: Number of G: Grouping mismatched lines factor 1 to 3 2 4 to 9 3 10 to 31 4 32 to 99 5 100 to 315 6 316 to 999 7 1000 to 3161 8 3162 to 9999 9 With the default dynamic grouping, the -g option sets the lower limit for G (which must be at least 2, because the formula is always applied). The -s option lets you fix G as a static constant. A static G may be desirable under some circumstances, but may also resynchronize the files at undesirable points, especially if G is too small. It’s recommended that you use the default (dynamic G ) first; if the results aren’t satisfactory, try a higher minimum value of dynamic G (such as 3 or 4). If that is still unsatisfactory, try the static G option. With either option, there’s a limit on the depth of the stacks— that is, on how far out of synchronization the two files can get before they’re no longer worth comparing. For a dynamic G, the limit on the number of mismatched lines is 1000, but you can choose a lower limit with the -d option. For the static G option, typical values for G are 1 to 5, and the stack depth should be between about 10 and 50 (the default limit is 25). Examples Compare File File.bak > Mismatches Compares File and File.bak, writing the results to the file Mismatches. No options are specified, so dynamic grouping is used, blanks are retained, tabs are expanded into spaces, and matching is case sensitive. Compare File.old.§ File.new.§ Compares the selected portions of the two windows and writes out the results. Limitations Compare can handle text files with a maximum line length of 255 characters. The text files compared should be fewer than 9999 lines long, because the displays are formatted based on four-digit line numbers. See also Equal command (Equal is a quicker command that tells you whether files are different, but stops at the first byte at which they differ). æKY CompareFiles æC CompareFiles -- compare text files and interactively view differences CompareFiles [-9 | -13 | -b x y | -Portrait | -TwoPage] oldFile newFile -9 # assume a screen size of 512 x 342 -13 # assume a screen size of 640 x 480 -b x y # tile windows into the rectangle specified by x y -Portrait # screen size for Apple Macintosh Portrait Display -TwoPage # screen size for Apple Two-Page Monochrome Monitor Status codes returned: 0 The files match. 1 Syntax error. 2 The files differ. Description CompareFiles compares two text files (using the tool Compare) and, if there are any differences, displays the file in adjacent windows for interactively viewing the differences. A menu will be appended to the menu bar to go through the changes. When all the changes have been shown, the windows will be closed (if they were closed when CompareFiles started) and the menu will be deleted. The Compare menu contains four items for viewing and editing the differences. The items perform the following actions: Find Next Change Finds the next difference and highlights the changes in each window. (Notice that the differences are shown from bottom to top. This is so editing changes will not affect the file offsets recorded from the Compare tool.) Copy Selection »» Replaces the changed text in the new file with the old text. Copy Selection «« Replaces the old text with the changed text from the new file. Done Closes the files (asking if you want to save changes) and deletes the Compare menu. Use this item to close all the windows and delete the menu. (If you close any of the windows yourself, they will not be restored to their previous size and position.) The figure below shows the CompareFiles menu. Examples CompareFiles Sample.old Sample.c Compares the file Sample.c to Sample.old. If there are some differences, those two files are opened side by side on the screen. CompareFiles -b 1024 1024 Sample.old Sample.c Compares the file Sample.c to Sample.old. If there are differences, the files are opened and tiled into a 1024 by 1024 rectangle. See also Compare Tool. æKY CompareRevisions æC CompareRevisions -- compare two revisions of a file in a project CompareRevisions file… Status codes returned: 0 No Errors. 1 Syntax Error. 2 Error in Processing. 3 System Error. Description Compare the revision of the HFS file file with another revision of that same file. CompareRevisions uses the ProjectInfo command to determine what project file belongs to and what its revision is. CompareRevisions then displays a list of the other revisions of the file for the user to choose. CompareRevisions checks this other revision out and calls the CompareFiles script to display both revisions on the screen and to highlight the differences between them. CompareFiles puts up an AddMenu named Compare to help you step through the differences between the two revisions. The file must belong to a currently mounted project. If the project that the file belongs to is not currently mounted, CompareRevisions displays an Alert. CompareRevisions uses the CompareFiles script. Examples CompareRevisions file.c This example compares the revision in HFS file "file.c" in the working directory with any other revisions of file.c in the project. AddMenu Project 'Compare Revisions' 'CompareRevisions {Active} ∑∑ {WorkSheet}' This example adds CompareRevisions to the Project menu and allows you to compare revisions by opening the file you wish to compare and then selecting the 'Compare Revisions' menu item in the Project menu. See also CompareFiles. æKY Confirm æC Confirm -- display a confirmation dialog box Confirm [-t] [message…] < file -t # three buttons (Yes, No, Cancel) Status codes returned: 0 The OK button was selected. 1 Syntax error. 4 The Cancel button was selected or the No button was clicked in a three-way dialog box. 5 The Cancel button was selected in a three-way dialog box; see the -t option. Description Confirm displays a confirmation dialog box with OK and Cancel buttons and the prompt message. There is no output to this command: the result of the dialog is returned in the {Status} variable. Note: Because Confirm returns a nonzero status value to indicate that No or Cancel was selected, a script should set the Shell variable {Exit} to zero before executing the Confirm command. (This step is necessary because the Shell aborts script processing when a nonzero status value is returned and {Exit} is nonzero.) Examples Set Exit 0 Confirm "Replace files with the same name? " If {Status} == 0 Duplicate -y Source:≈ Destination: End Set Exit 1 The following confirmation dialog box will be displayed: æKY Continue æC Continue -- continue with next iteration of For or Loop Continue [If expression] Status codes returned: 0 No errors. –3 Error in parameters, or Continue not within For…End or Loop…End. –5 Invalid expression. Description If expression is nonzero, Continue terminates this iteration of the immediately enclosing For or Loop command and continues with the next iteration. (Null strings evaluate to zero.) If the "If expression" clause is omitted, the Continue is unconditional. If no further iterations are possible, the For or Loop is terminated. (For a definition of expression, see the Evaluate command.) Examples Set Exit 0 Set list "" For file In `files -t TEXT` Confirm -t "Print file {file}?" Set SaveStatus {Status} Continue If {SaveStatus} == 4 # No Break If {SaveStatus} == 5 # Cancel Set list "{list} '{file}'" # YesEnd End Print {PrintOptions} {list} Set Exit 1 In this example, the Continue command is executed if the user selects No (status value 4). The Continue causes the current file to be skipped, but processing continues with the next file in the list. (For a full explanation of this example, refer to the Confirm command.) See also For, Loop, Break, and If commands. Evaluate command, for a description of expressions. "Structured Commands" in Chapter 5. æKY Copy æC Copy -- copy selection to Clipboard Copy [-c count] selection [window] -c count # copy the nth selection, where n = count Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Any other error. Description Finds selection in the specified window and copies it to the Clipboard, replacing the previous contents of the Clipboard. If no window is specified, the command operates on the target window (the second window from the front). It’s an error to specify a window that doesn’t exist. For a definition of selection, see "Selections" in Chapter 6 of the MPW manual; a summary of the selection syntax is contained in Appendix B. • Note: To copy files, use the Duplicate command. Examples Copy § Copies the current selection to the Clipboard. This command is like the Copy command in the Edit menu, except that the action takes place in the target window. Copy /BEGIN/:/END/ Selects everything from the next BEGIN through the following END and copies this selection to the Clipboard. See also Cut and Paste commands. "Selections" in Chapter 6 and Appendix B. æKY Count æC Count -- count lines and characters Count [-l] [-c] [file…] < file > counts -l # write only line counts -c # write only character counts Status codes returned: 0 No errors. 1 Error in parameters. 2 Unable to open input file. Description Counts the lines and characters in its input and writes the results to standard output. If no files are specified, standard input is read. If more than one file is specified, separate counts are printed for each file, one per line and preceded by the filename. A total is printed following the list. Examples Count MakeFile.c Count.c Displays line counts and character counts in the form MakeFile.c 43 981 Count.c 153 3327 Total 196 4303 Files | Count -l Displays the total number of files and directories in the current directory. Count -l § Displays the number of lines selected in the target window. • Note: The source code for Count is included in the CExamples folder in the file Count.c, as part of MPW C. æKY CPlus æC CPlus -- script to compile C++ source CPlus [option…] [file…] < file > intermediate output ≥ progress -a # force ANSI-style intermediate C code (default) -a0 # force K&R-style (pre-ANSI) intermediate C code -a1 # force ANSI-style intermediate C code (default) -b # put string constants into code and generate PC-relative references -b2 # implies '-b' above, and allows string constants to be overlaid -b3 # overlaid string constants in code (but not PC-relative refs.) -c # intermediate code to standard output; no object file -d name # equivalent to: #define name 1 -d name=string # equivalent to: #define name string -e # write preprocessor results to output -e2 # implies '-e' above, and strips comments -elems881 # generate MC68881 code for transcendentals -f filename # act as if input comes from named file when it actually is from stdin -f1 # send text version of C code to C compiler (no token stream) -i directory # search for includes in directory -m # generate 32-bit references for data (less efficient code) -mbg ch8 # MPW 2.0 compatible macsbug symbols -mbg off # no macsbug symbols in the code (link/unlk only if necessary) -mbg on|full # full macsbug symbols -mbg <n> # macsbug symbols to length <n> (<n> can be 0..63) -mc68020 # generate MC68020 code -mc68881 # generate MC68881 code for arithmetic operations -mtbl0 # suppress output of method tables for Object Pascal Classes -mtbl1 # force output of method tables for Object Pascal Classes -n # Turn pointer assignment incompatibilty errors into warnings -o objname # generate code in file or directory objname -p # write progress information to diagnostic -s segment # generate code in segment -sym off # no SADE records -sym on|full # full SADE records; can modify with [,nolines] [,notypes] [,novars] -t # write C compilation time to diagnostic -u name # equivalent to: #undef name -vtbl0 # suppress output of virtual tables for ordinary class -vtbl1 # force output of virtual tables for ordinary class -vtbl2 # new improved output algorithm for virtual tables -w # suppress warnings -w1 # generate additional warnings from CFront -w3 # passed through to C compiler (supresses unused warnings) -y directory # create temporary files in directory -z0 # force 'inline' functions to be non-inline -z3 # supress name encoding of local vars and struct members (default) -z4 # encode names of local vars and struct members -z6 # force enums always to be int variables -z7 # relax requirement on static class member initialization Status codes returned: 0 Successful completion. 1 Errors occurred. Description CPlus compiles the specified C++ source file. Compiling file Name.cp creates object file Name.cp.o. (By convention, C++ source filenames end in a ".cp" suffix.) If no filenames are specified, standard input is compiled and the object file "c.o" is created. (Note that SADE object file information cannot be generated for standard input source files.) The CPlus script activates, in turn, CFront, and the MPW C Compiler. (CFront consists of two components: a C preprocessor and a C++ to C translator.) See the MPW 3.0 C++ Reference Manual for details of the MPW C++ language definition. Examples cplus -p Sample.c Compiles Sample.c, producing the object file Sample.c.o. Writes progress information to diagnostic output. (Sample.c is found in Examples:CPlusExamples.) See also MPW 3.0 C Reference, MPW C++ Reference. æKY CreateMake æC CreateMake -- create a simple makefile CreateMake [ -Application [ -c creator ] | -Tool | -DA | SIOW -CR -m mainEntryPoint -rt resourceType | -SIOW [ -t type ] [ -c creator ] ] [-sym on] [-mc68020 | -mc68881 | -elems881] program file… -Application # create an Application (default) -c creator # optional Creator for Application or Code Resource -Tool # create a Tool -DA # create a Desk Accessory -CR # create a Code Resource -SIOW # create a Simple Input/Output Window -m mainEntryPoint # required Main Entry Point for Code Resource -rt resourceType # required Resource Type for Code Resource -t type # optional File Type for Code Resource -sym on # include SADE information in the object file -mc68020 # generate 68020 instructions -mc68881 # generate 68881 instructions for elementary operations -elems881 # generate 68881 instructions for transcendental functions Status codes returned: 0 Successful completion. 1 Parameter or option error. Description CreateMake creates a simple makefile for building the specified program. The parameter program is the name of the program. Makefile program.make is created. The list of files includes both source and library files. Source files may be written in any combination of assembly language (suffix ".a"), C (".c"), C++ (".cp"), Pascal (".p"), and/or Rez (".r"). You can also specify Library files (suffix ".o"). Link the program with these files. CreateMake automatically links with the library files listed below. It is not necessary to specify these files as parameters to CreateMake. You can create Makefiles for building applications (the default), desk accessories, and tools. CreateMake generates commands that link the program with the following set of MPW libraries: • Inside Macintosh Interfaces {Libraries}Interface.o • Runtime support—one of the following: {Libraries}Stubs.o # a tool is to be built {Libraries}Runtime.o # no C object files {CLibraries}CRuntime.o # any C object files • C Libraries—if any source is in C {CLibraries}StdCLib.o {CLibraries}CSANELib.o {CLibraries}Math.o {CLibraries}CInterface.o • C Libraries—if any source is in C++ {CLibraries}CPlusStreams.o # a tool is to be built {CLibraries}CPlusStubs.o # a DA is to be built {CLibraries}CSANELib.o {CLibraries}Math.o {CLibraries}CInterface.o • Pascal Libraries—if any source is in Pascal {PLibraries}PasLib.o {PLibraries}SANELib.o • For tools: {Libraries}ToolLibs.o • For desk accessories: {Libraries}DRVRRuntime.o CreateMake does not include dependencies on include files and USES files in the makefile. Libraries other than those listed above are not included in the Link command generated by CreateMake, unless specified as parameters. CreateMake is used to implement the Create Build Commands item in the Build menu. Examples CreateMake -tool count count.c count.r Creates the makefile Count.make containing commands for building the tool Count from the source files Count.c and Count.r. The makefile is similar to the following: # File: count.make # Target: count # Sources: count.c count.r # Created: Thursday, June 2, 1988 5:33:38 PM count.c.o ƒ count.make count.c C count.c count ƒƒ count.make count.r Rez count.r -append -o count SOURCES = count.c count.r OBJECTS = count.c.o count ƒƒ count.make {OBJECTS} Link -w -t MPST -c ‘MPS ’ ∂ "{Libraries}"Stubs.o ∂ "{CLibraries}"CRuntime.o ∂ "{Libraries}"Interface.o ∂ "{CLibraries}"StdCLib.o ∂ "{CLibraries}"CSANELib.o ∂ "{CLibraries}"Math.o ∂ "{CLibraries}"CInterface.o ∂ "{Libraries}"ToolLibs.o ∂ "{OBJECTS}" ∂ -o count See also BuildMenu and BuildProgram commands. "Building a Program: An Introduction" in Chapter 2. æKY Cut æC Cut -- copy selection to Clipboard and delete it Cut [-c count] selection [window] -c count # cut the next count selections Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Any other error. Description Finds selection in the specified window, copies its contents to the Clipboard, and then deletes the selection. If no window is specified, the command operates on the target window (the second window from the front). It’s an error to specify a window that doesn’t exist. For a definition of selection, see "Selections" in Chapter 6 of the MPW manual; a summary of the selection syntax is contained in Appendix B. Examples Cut § Cuts the current selection in the target window. (This is the same as the Cut menu item, except that it operates on the target window rather than the active window.) Cut /BEGIN/:/END/ Selects everything from the next BEGIN through the following END, copies the contents of the selection to the Clipboard, and then deletes the selection. See also Clear, Copy, and Paste commands. "Selections" in Chapter 6 and in Appendix B. æKY Date æC Date -- write the date and time Date ([-a | -s] [-d | -t] [-c seconds]) | [-n] > date -a # abbreviated date (e.g. Wed, Jun 18, 1986) -s # short date (e.g. 6/18/86) -d # write date only -t # write time only -c seconds # write date corresponding to seconds -n # write seconds since January 1, 1904 Status codes returned: 0 No error. 1 Syntax error. Description Writes the current date and time to standard output in a variety of standard and user-specified formats. Date arithmetic is supported with the -n and -c options that work with the number of seconds since January 1, 1904. With no options the Date output has this form: Thursday, August 30, 1988 10:45:51 A.M. Examples Date returns the date in the form Friday, February 14, 1988 10:34:25 PM Date -a returns Fri, Feb 14, 1988 10:34:25 PM Date -s -d returns 2/14/86 Set starttime `Date -n` BuildMyProgram Set endTime `Date -n` Echo Total time for BuildMyProgram ∂ `Evaluate {endTime} - {startTime}` This example demonstrates how date arithmetic may be used to show how long a tool or script takes to execute. æKY Delete æC Delete -- delete files and directories Delete [-y | -n | -c] [-i] [-p] name… ≥ progress -y # delete directory contents (avoids dialog) -n # don't delete directory contents (avoids dialog) -c # cancel if a directory is to be deleted (avoids dialog) -i # ignore errors (no diagnostics) -p # write progress information to diagnostics Status codes returned: 0 All specified objects were deleted (except for any directories skipped with the -n option). 1 Syntax error. 2 An error occurred during the delete. 4 Cancel was selected or implied by the -c option. Description Deletes file or directory name. If name is a directory, name and its contents (including all subdirectories) are deleted. Before deleting directories, a dialog box will request confirmation for the deletion. Use the -y, -n, or -c options in scripts to avoid this interaction. Be sure to see the warning at the end of this section. Examples Delete HD:MPW:≈.c Deletes all items in the MPW folder that end in ".c". (Recall that the Shell first replaces the parameter "≈.c" with a list of filenames matching the pattern—the Delete command then deletes each of these files.) Warning Beware of potentially disastrous typographical mistakes such as the following: Delete ≈ .c Note the space after "≈"—this space causes "≈" and ".c" to be treated as two separate parameters. In this case, Delete deletes all files in the current directory and also attempts to delete a file named ".c". Also note that the following command deletes everything: Delete ≈: That is, the filename pattern ≈: expands to the names of all volumes online (including the startup volume!). When deleting files en masse, it’s a good practice to use the Echo command to verify the action of the filename generation operators; for example, Echo ≈.c See also Clear command (for deleting selections). "Filename Generation" in Chapter 5. æKY DeleteMenu æC DeleteMenu -- delete user-defined menus and menu items DeleteMenu [menuName [itemName]] Status codes returned: 0 No errors. 1 Syntax error. 2 Other errors. Description Deletes the user-defined item itemName in the menu menuName. If itemName is omitted, all user-defined items for menuName are deleted. Caution If itemName and menuName are both omitted, all user-defined items are deleted. Menu items that haven’t been added with AddMenu can’t be deleted with DeleteMenu. Examples DeleteMenu File Deletes all user-defined items from the File menu. See also AddMenu command. æKY DeleteNames æC DeleteNames -- delete user-defined symbolic names DeleteNames [-u user] [-private] [-project project] [-public] [-r] [names… | -a] -u user # name of current user -private # delete private names -project project # name of project that contains the files -public # delete public names -r # delete names recursively -a # delete all names Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. Description Delete symbolic names used to represent a set of revisions under Projector. You can create symbolic names by using the NameRevisions command. You can use the -log option of the ProjectInfo command to see which names have been deleted and what their values were. See Chapter 7 of MPW Manual for complete definitions of the terms and symbols used in Projector commands. Examples Suppose you have created a Name "Work" that is expanded to the files file.c and interactive.c using the command NameRevisions Work file.c interactive.c Then: DeleteNames Work removes "Work" from the list of symbolic names. See also NameRevisions, ProjectInfo. æKY DeletePane æC DeletePane -- delete panes from the window DeletePane [-p paneSpec | -a] [window] -p paneSpec # choose a pane to delete -a # reset the window to one pane Note: paneSpec is an alternating catenation of strings of the form cm and rn, where m is a column ordinal and n is a row ordinal. æKY DeleteRevisions æC DeleteRevisions -- delete previous revisions of files in a project DeleteRevisions [-u user] [-project project] [-file] [-y] revision… -u user # name of current user -project project # name of project that contains the files -file # deletes the file and all its revisions -y # delete the file/revision (avoids dialog) Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Delete old revisions by specifying the oldest revision that you want to keep. All prior revisions are deleted. Delete all revisions on a branch by naming the branch or branches in the named files under Projector. It is an error to try to delete a revision that is currently checked out for modification. Revision is either a filename, a filename followed by a comma and a revision number, or a filename followed by a comma and a branch name (such as foo.c,22a). You can use the -file option to remove the file and all of its revisions from the project. s Warning DeleteRevisions permanently removes the revisions and branches specified. They cannot be recovered. s You can use the -log option of the ProjectInfo command to see which revisions have been deleted and who deleted them. See Chapter 7 of the MPW Manual for complete definitions of the terms and symbols used in Projector commands. Examples DeleteRevisions -project Zoom∫Utilities∫MyProject file.c This example deletes all revisions except the latest in file.c in the named project. DeleteRevisions file.c,22a3 This example deletes all revisions on branch 22a before revision 3 of file.c. DeleteRevisions file.c,22a This command deletes all the revisions on branch 22a in file.c of the current project. DeleteRevisions -file file.c This command deletes the file file.c and all of its revisions from the current project. See also NameRevisions, ProjectInfo. æKY DeRez æC DeRez -- resource decompiler DeRez [option…] resourceFile [file…] > description ≥ progress -c[ompatible] # generate output compatible with Rez 1.0 -e[scape] # don't escape chars < $20 or > $D8 -d[efine] name[=value] # equivalent to #define name [value] -i[nclude] pathname # search this path when looking for #include files -m[axstringsize] n # write strings n characters per line -only typeExpr # process only resources of this type -p[rogress] # write progress information to diagnostics -rd # suppress warnings for redeclared types -s[kip] typeExpr # skip resources of this type -u[ndef] name # equivalent to #undef name Note: A typeExpr may have one of these forms: type "'type'(id)" "'type'(id:id)" "'type'(∂"name∂")" Status codes returned: 0 No errors. 1 Error in parameters. 2 Syntax error in file. 3 I/O or program error. Description Creates a text representation (resource description) of the resource fork of resourceFile, according to the resource type declarations in the resource description file(s). The resource description is written to standard output. A resource description file is a file of type declarations in the format used by the resource compiler, Rez. The type declarations for standard Macintosh resources are contained in the files Types.r and SysTypes.r, contained in the {RIncludes} folder. If no resource description file is specified, the output consists of data statements giving the resource data in hexadecimal form, without any additional format information. If the output of DeRez is used as input to Rez, with the same resource description files, it produces the same resource fork that was originally input to DeRez. DeRez is not guaranteed to be able to run a declaration backwards; if it can’t, it produces a data statement instead of the appropriate resource statement. DeRez ignores all include (but not #include), read, data, change, delete, and resource statements found in the resourceDescriptionFile. (It still parses these statements for correct syntax.) For the format of resource type declarations, see Chapter 11 and Appendix D of the MPW manual. Examples DeRez "{ShellDirectory}MPW Shell" -only MENU Types.r Displays all of the 'MENU' resources used by the MPW Shell. The type definition for 'MENU' resources is found in the file Types.r. DeRez HD:OS:System SysTypes.r ∂ -only "'DRVR' (∂"\\0x00Scrapbook∂")" Decompiles the Scrapbook desk accessory in the copy of the System file that’s located in directory HD:OS:. (The type definition for 'DRVR' resources is found in the file SysTypes.r.) See also Rez and RezDet commands. Chapter 11. Type declaration files in RIncludes folder: • Types.r • SysTypes.r • MPWTypes.r • Pict.r æKY Directory æC Directory -- set or write the default directory Directory [-q | directory] > directory -q # don't quote directories with special characters Status codes returned: 0 No error. 1 Directory not found, command aborted, or parameter error. Description If specified, directory becomes the new default directory. Otherwise the pathname of the current default directory is written to standard output. If directory is a leafname, the command searches for directory in the directories listed in the Shell variable {DirectoryPath}. If the variable is undefined, the command looks in the current directory. • Note: To display a directory’s contents, use the Files command. Examples Directory Writes the pathname of the current directory to standard output. Directory HD:MPW:Examples: Sets the default directory to the folder Examples in the folder MPW on the volume HD. The final colon is optional. Directory Reports: Sets the default directory to the volume Reports. Note that volume names must end in a colon. Directory :Include:Pascal: Sets the default directory to the folder Pascal in the folder Include in the current default directory. Set DirectoryPath ":, {MPW}, {MPW}Projects:" Directory Tools Sets the directory to the Tools directory. The current directory is searched first, followed by the {MPW} directory, and finally by the {MPW} Projects directory. If there is no Tools directory in your current directory, the directory is set to {MPW}Tools. See also "File and Window Names" in Chapter 4. Files, NewFolder, and SetDirectory commands. æKY DirectoryMenu æC DirectoryMenu [directory…] -- create the Directory menu Status code returned: 0 no errors always returned. Description Creates the Directory menu shown here. The optional directory… parameter specifies the initial list of directories that appears in the menu. The menu items are described in Chapter 3 of the MPW manual. The lower section of the Directory menu contains a list of directories. Initially this list consists of the parameters to DirectoryMenu. As other directories become the current directory (using the Set Directory menu item or the SetDirectory command), they are added to the list. Examples DirectoryMenu `(Files -d -i {MPW}Examples:≈) ≥ Dev:Null` `Directory` Creates the Directory menu. Directories in directory {MPW} that match the pattern Examples:≈ will be included in the Directory menu, along with the current directory. This DirectoryMenu command should be included in your UserStartup file to install the Directory menu. You might replace the Examples directories and the default directory with your favorite list of directories. æKY DoIt æC DoIt -- highlight and execute a series of shell commands DoIt (CommandFile [-echo] [-dump]) | [-selection] -echo # echo commands before execution -dump # dump unexecuted commands after error -selection # execute command in the current selection Status codes returned: 0 No errors. 1 Syntax error. Description DoIt will execute a series of Shell commands, highlighting each command as it is executed. The commands can be either in a file or in the current selection of the active window. If a CommandFile is passed to DoIt, the file is opened (as the active window) and each command is executed. The window is closed when all commands have been processed. This command will not work for a series of commands that contains structured commands such as If statements or Loops. Examples Backup -from "HD:Src:" -to "Backup:Src" -a -r -c > out DoIt out The above command will highlight and execute all the Duplicate commands generated by the Backup command. In this way you can see progress as the files are being duplicated. AddMenu DoIt "DoIt Selection" "DoIt -selection" The above AddMenu command will create a menu that can be used to highlight and execute the current selection. This could be used on a series of commands generated by Make or Backup that were written to the Active window. Simply select the commands and select the "DoIt Selection" menu item. Make > make.out DoIt -dump make.out This DoIt command will open the make.out file and highlight and execute each of the commands generated by the previous make command. In this way you can see progress as the files are being compiled and linked. If an error occurs (for instance, in one of the compiles), that compile command along with the rest of the commands in the make.out will be written to the WorkSheet. At this point you could fix the error (in the source file), select the "ToDo" marker (which would select the remaining commands), and select the "DoIt Selection" menu item to execute the remaining commands. æKY DumpCode æC DumpCode -- write formatted CODE resources DumpCode [option…] resourceFile > dump ≥ progress -a # Show offsets from beginning of segment -d # don't dump object code -di # don't dump data initialization info -h # don't write headers (offsets, hex, etc.) -jt # don't dump jump table -n # dump only resource names -p # write progress information to diagnostics -r byte1[,byte2] # dump code from address byte1 (through byte2) -ri # don't dump a5- and segment-relocation info -rt type[=id] # dump only resources with this type (and id) -s name # dump only resource with this name Status codes returned: 0 No problem. 1 Syntax error. 2 Fatal error. Description Disassembles object code that is stored in resources such as 'CODE', 'DRVR', and 'PDEF'. DumpCode reads from the resource fork of the specified file and writes the formatted assembly code to standard output. The default formatting convention is to disassemble the code and to display the corresponding bytes in hexadecimal and ASCII. The default behavior of DumpCode is to dump all the 'CODE' resources from a program file. The -rt option can be used to dump resources of other types, such as drivers and desk accessories. Some conventions about executable code resources are built into DumpCode and affect the formatted output in special ways: • 'CODE' resources with ID 0 are formatted as a jump table (unloaded format). • Other 'CODE' resources have information about jump table entries in the first four bytes. • 'DRVR' resources have a special format at the beginning of the resource. In addition, you can direct DumpCode to give a symbolic dump of data initialization descriptors and initial values. Examples DumpCode Sample > SampleDump Formats the 'CODE' resources in the file Sample, writing the output to the file SampleDump. The output has this format: File: sample, Resource 3, Type: CODE, Name: _DataInit Offset of first jump table entry: $00000018 Segment is $000000D2 bytes long, and uses 1 jump table entry 000000: 48E7 FFF0 'H...' MOVEM.L D0-D7/A0-A3,-(A7) 000004: 4247 'BG' CLR.W D7 000006: 4EAD 0032 'N..2' JSR $0032(A5) 00000A: 2218 '".' MOVE.L (A0)+,D1 etc. See also DumpObj command. "The Jump Table" in the chapter "Segment Loader" of Inside Macintosh, for a description of the jump table. Appendix H, "Object File Format." æKY DumpFile æC DumpFile -- display contents of any file DumpFile [ option… ] filename > dump ≥ progress -rf # display the resource fork of the file. (Default is # data fork.) -bf # display both forks of the file -a # suppress display of ASCII character values. -h # suppress display of hexadecimal characters. -o # suppress display of file offsets. -w nn # width - display nn bytes on each line of output. -g nn # group nn bytes together without intervening spaces. -p # write progress information to diagnostic output. -r byte1[,byteN] # display only the byte range from byte1 to byteN. Status codes returned: 0 No problem. 1 Syntax error. 2 Fatal error. Description DumpFile lets you display the contents of the resource fork or data fork of a file in a variety of formats. Examples DumpFile -p ATestFile Formats the data fork of the file ATestFile and writes its contents to standard output. This output has the following format: DumpFile -p ATestFile MPW File Display Utility Version 3.0B1 Release April 15, 1988 Start: 1:24:09 PM 4/19/88 Copyright Apple Computer, Inc. 1985-1988 All Rights Reserved. File : ATestFile Data Fork Length : 20 Resource Fork Length : 382 Dumping Data Fork from offset 0 to 20 0: 54 68 69 73 20 69 73 20 61 20 74 65 73 74 20 66 This.is.a.test.file. 10: 69 6C 65 2E DumpFile completed normally Execution required 0 seconds. DumpFile -w 12 -g 4 ATestFile Formats the data fork of the file ATestFile and writes its contents to standard output, grouping four bytes at a time and displaying 12 bytes per line. This output has the following format: File : ATestFile Data Fork Length : 20 Resource Fork Length : 382 Dumping Data Fork from offset 0 to 20 0: 54686973 20697320 61207465 This.is.a.te C: 73742066 696C652E st.file. DumpFile -rf -r 0,30 -g 4 ATestFile Formats the resource fork of the file ATestFile and writes the contents of bytes 0 through 30 to standard output in 4-byte groups. This output has the following format: File : ATestFile Data Fork Length : 20 Resource Fork Length : 382 Dumping Resource Fork from offset 0 to 30 0: 00000100 0000014C 0000004C 00000032 .......L...L...2 10: 696C652E 6F727920 2227227B 646972 ile.ory."'"{dir æKY DumpObj æC DumpObj -- write formatted object file DumpObj [option…] objectFile > dump ≥ progress -d # don't dump object code -h # don't write headers (offsets, hex, etc.) -i # use ids, rather than names, in dump -jn # just use names, rather than ids, in dump -l # dump file locations of object records -m name # dump only module "name" or module containing # entry-point "name" (-m option may be used repeatedly) -n # dump only the dictionary of names -p # write progress information to diagnostics -r byte1[,byte2] # dump code from byte1 in file (through byte2) -mh # omit module summary header -mods # dump a module summary with entry point information -sym [Off] # disable symbolic output [On | Full] # enable symbolic output (default), can be followed by: [,NoLabels] # omit label information [,NoLines] # omit source line information [,NoTypes] # omit type information [,NoVars] # omit variable information Status codes returned: 0 No problem. 1 Syntax error. 2 Fatal error. Description Disassembles object code that is stored in the data fork of an object file. By convention, object files end in the suffix ".o". In addition, the object file must have type 'OBJ'. Examples DumpObj Sample.p.o >SampleDump Formats the file Sample.p.o and writes its contents to the file SampleDump. This output has the following format: Dump of file sample.p.o First: Kind 0 Version 1 Dictionary: FirstId 2 2: Main Pad Module: Flags $00 ModuleId 1 SegmentId Main Content: Flags $00 Contents offset 0000 size 006A 000000: 4E56 FFFE 'NV..' LINK A6,#$FFFE 000004: 2F07 '/.' MOVE.L D7,-(A7) 000006: 42A7 'B.' CLR.L -(A7) 000008: 3F3C 0080 '?<..' MOVE.W #$0080,-(A7) etc. For more information, see Appendix H. See also DumpCode command. Appendix H, "Object File Format." æKY Duplicate æC Duplicate -- duplicate files and directories Duplicate [-y | -n | -c] [-p] [-d | -r] name… target ≥ progress -y # overwrite target files (avoids dialog) -n # don't overwrite target files (avoids dialog) -c # cancel if conflict occurs (avoids dialog) -p # write progress information to diagnostics -d # duplicate data fork only -r # duplicate resource fork only Status codes returned: 0 All objects were duplicated. 1 Syntax error. 2 An error occurred. 4 Cancel was selected or implied from the -c option. Description Duplicates name to targetName. (Name and targetName are file or directory names.) If targetName is a file or doesn’t exist, the file or directory name is duplicated and named targetName. If targetName is a directory, the objects named are duplicated into that directory. (If more than one name is present, targetName must be a directory.) Created objects are given the same creation and modification dates as their source. If a directory is duplicated, its contents (including all subdirectories) are also duplicated. No directory duplicated can be a parent of targetName. Name can also be a volume; if targetName is a directory, name is copied into targetName. A dialog box requests a confirmation if the duplication would overwrite an existing file or folder. You can use the -y, -n, or -c option in scripts to avoid this interaction. Examples Duplicate Aug86 "Monthly Reports" Assuming "Monthly Reports" is an existing directory, duplicates the file Aug86 into that directory. Duplicate File1 Folder1 "Backup Disk:" Duplicates File1 and Folder1 (including its contents) onto Backup Disk. Duplicate -y File1 File2 Duplicates File1 to File2, overwriting File2 if it exists. Duplicate Disk1:≈ HD:Files: Duplicates all of the files on Disk1 into the directory HD:Files. Duplicate Disk1: HD:Files: Duplicates all of Disk1 (as a directory) into HD:Files. Limitation Duplicate doesn’t recognize folders on non-HFS disks. See also Move and Rename commands. "File and Window Names" in Chapter 4. "Filename Generation" in Chapter 5. æKY Echo æC Echo -- echo parameters Echo [-n] [parameter…] > parameters -n # don't write return following the parameters Status codes returned: 0 is always returned. Description Writes its parameters, separated by spaces and terminated by a return, to standard output. If no parameters are specified, only a return is written. Echo is especially useful for checking the results of variable substitution, command substitution, and filename generation. Examples Echo "Use Echo to write progress info from scripts." Use Echo to write progress info from scripts. The Echo command above writes the second line to standard output. Echo {Status} Writes the current value of the {Status} variable—that is, the status of the last command executed. Echo ≈.a Echoes the names of all files in the current directory that end with ".a". (This might be useful as a precaution before executing another command with the argument "≈.a".) Echo -n > EmptyFile If EmptyFile exists, this command deletes its contents; if the file doesn’t exist, it is created. See also Parameters and Quote commands. æKY Eject æC Eject -- eject volumes Eject [-m] volume… -m # leave the volume mounted Status codes returned: 0 The disk was successfully ejected. 1 Syntax error. 2 An error occurred. Description Flushes the volume, unmounts it, and then ejects it, if it is a 3.5-inch disk. A volume name must end with a colon ( : ). If volume is a number without a colon, it’s interpreted as a drive number. • Note: If you unmount the current volume (the volume containing the current directory), the boot volume becomes the current volume. You can keep the volume mounted with the -m option. (See the chapter "File Manager" of Inside Macintosh.) Examples Eject Memos: Ejects (and unmounts) the disk titled Memos. Eject 1 Ejects and unmounts the disk in drive 1 (the internal drive). See also Mount, Unmount, and Volumes commands. æKY Entab æC Entab -- convert runs of spaces to tabs Entab [option…] [file…] < file > tabbed ≥ progress -a minValue # Min run of blanks that can be replaced with a tab -d tabValue # input tab setting -l quote… # left quotes that prevent EnTab (default '") -n # no quote characters, EnTab everything -p # write progress information to diagnostics -q quote… # quotes that prevent EnTab (default '") -r quote… # right quotes that prevent EnTab (default '") -t tabValue # output tab setting Status codes returned: 0 Normal termination. 1 Parameter or option error. Description Copies the specified text files to standard output, replacing runs of spaces with tabs. The default behavior of Entab is to do the following: 1. Detab the input file, using the file’s tab setting (a resource saved with the file by the Shell editor), or 4 if there is none. You can override this "detab" value with the -d option. 2. Entab the file, setting tab stops every 4 spaces. You can specify another tab setting with the -t option. The entabbed output file looks the same as the original file(s), but contains fewer characters. Options are also provided for controlling the processing of blanks between quoted strings. Examples Entab -t 2 Example.p > CleanExample.p Detabs the file Example.p (using the file’s default tab setting), re-entabs it with a tab setting of 2, and writes the resulting output to CleanExample.p. Warning Beware of command formats such as Entab Foo > Foo Limitations Entab does not take into account embedded formatting characters other than tab characters. Thus backspace characters may cause incorrect results. The maximum width for an input line is 255 characters. See also Format command. æKY Equal æC Equal -- compare files and directories Equal [-d | -r] [-i] [-p] [-q] name… target > differences ≥ progress -d # compare data forks only -r # compare resource forks only -i # ignore files in target not in directory name -p # write progress information to diagnostics -q # quiet - don't write output, just set {Status} Status codes returned: 0 Identical files. 1 Syntax error. 2 Inaccessible or missing parameter. 3 Files not equal. Description Compares name to targetName. By default, Equal makes no comment if files are the same; if they differ, it announces the byte at which the difference occurred. When comparing directories, the default condition is to report all differences, including files not found—the -i option ignores files in targetName that are not present in name. If targetName is a file, every name must also be a file. The specified files are compared with targetName. If targetName is a directory and name is a file, Equal checks in targetName for the file name and compares the two files. That is, the command Equal File1 Dir1 compares File1 with :Dir1:File1. If more than one name is specified, Equal compares each name with the corresponding file or directory in targetName. All subdirectories are also compared. For example, Equal File1 Dir1 Dir2 If targetName is a directory, name is a directory, and only one name is specified, the Equal command directly compares the two directories. That is, the command Equal Dir1 Dir2 compares Dir1 (and all subdirectories) with Dir2. Examples Equal File1 File1Backup Reports if the files are different and at what point they differ, in a message such as File1 File1Backup differ in data fork, at byte 5 Equal -i HD:Dir1 Disk1:Dir1 Compares all files and directories in HD:Dir1 with files and directories with the same names found in Disk1:Dir1, and reports any differences. This command does not report files in Disk1:Dir1 that aren’t found in HD:Dir1. Equal -i -d Backup: HD:Source Compares the data forks of all files on the volume Backup: with all those of the same name in the directory HD:Source. Equal -p Old:≈.c HD:Source Compares all files on Old: ending in ".c" with their counterparts in HD:Source. Prints progress information as the comparison proceeds. See also Compare command. æKY Erase æC Erase -- initialize volumes Erase [-y] [-s] volume… -y # yes - erase the disk (avoids dialog) -s # single-sided - 400K (default 800K) Status codes returned: 0 Successful initialization. 1 Syntax error. 2 No such volume, or boot volume. 3 Errors during the initialization procedure. Description Initializes the specified volumes— the previous contents are destroyed. A volume name must end with a colon ( : ). If volume is a number without a colon, it’s interpreted as a disk drive number. A dialog box requests confirmation before proceeding with the command, unless the -y option is specified. The -y option can be used in scripts to avoid this interaction. Examples Erase Reports: Initializes the volume entitled Reports. Erase 1 Initializes the volume in drive 1 (the internal drive). The disk will be formatted as a 400K disk if drive 1 is a 400K drive, or as an 800K disk if drive 1 is an 800K drive. æKY Evaluate æC Evaluate -- evaluate an expression Evaluate [-h | -o | -b] [word…] > value Evaluate Name [binary operator]= expression -h # display result in hexadecimal (leading 0x) -o # display result in octal (leading 0) -b # display result in binary (leading 0b) Status codes returned: 0 Valid expression. 1 Invalid expression. Description The list of words is taken as an expression. After evaluation, the result is written to standard output. Missing or null parameters are taken as zero. You should quote string operands that contain blanks or any of the characters listed in the table that follows. The operators and precedence are mostly those of the C language; descriptions follow. The second form of the Evaluate command evaluates the list of words and assigns the result to the variable name. The result of the expression is not written to standard output in this case. C style operations of the form "+=", "-=", and so on, are supported. If name is undefined at the time of execution, it is interpreted as zero. Different radices can be used in the input expression, and the result can be output in a different radix by using the -h, -o, or -b option. The default radix is decimal. Expressions: An expression can include any of the following operators. (In some cases, two or three different symbols can be used for the same operation.) The operators are listed in order of precedence; within each group, operators have the same precedence. Operator Operation 1. (expr) Parentheses are used to group expressions 2. - Unary negation ~ Bitwise negation ! NOT ¬ Logical NOT 3. * Multiplication ÷ DIV Division % MOD Modulus division 4. + Addition - Subtraction 5. << Shift left >> Shift right 6. < Less than <= ≤ Less than or equal to > Greater than >= ≥ Greater than or equal to 7. == Equal != <> ≠ Not equal =~ Equal—regular expression !~ Not equal—regular expression 8. & Bitwise AND 9. ^ Bitwise XOR 10. | Bitwise OR 11. && AND Logical AND 12. || OR Logical OR All operators group from left to right. Parentheses can be used to override the operator precedence. Null or missing operands are interpreted as zero. The result of an expression is always a string representing a number in the specified radix (the default is decimal). The logical operators !, NOT, ¬, &&, AND, | |, and OR interpret null and zero operands as false, and nonzero operands as true. Relational operators return the value 1 when the relation is true, and the value 0 when the relation is false. The string operators ==, !=, =~, and !~ compare their operands as strings. All others operate on numbers. Numbers may be decimal, hexadecimal, octal, or binary integers representable by a 32-bit signed value. Hexadecimal numbers begin with either $ or 0x. Octal numbers begin with a 0 (zero). Binary numbers begin with 0b. Every expression is computed as a 32-bit signed value. Overflows are ignored. Input Radices Decimal number [0–9] Hexadecimal number 0x[0–9A–F] Octal number 0[0–7] Binary number 0b[01] The pattern-matching operators =~ and !~ are like == and != except that the right side is a regular expression that is matched against the left operand. Regular expressions must be enclosed within the regular expression delimiters /…/. Regular expressions are summarized in Appendix B. • Note: There is one difference between using regular expressions after =~ and !~ and using them in editing commands. When evaluating an expression that contains the tagging operator, ®, the Shell creates variables of the form {®n}, containing the matched substrings for each ® operator. (See the examples that follow.) Filename generation, conditional execution, pipe specifications, and input/output specifications are disabled within expressions, to allow the use of many special characters that would otherwise have to be quoted. Expressions are also used in the If, Else, Break, Continue, and Exit commands. Examples Evaluate (1+2) * (3+4) Does the computation and writes the result to standard output. Evaluate -h 8 + 8 Does the computation and writes the result to standard output in hexadecimal (0x10). Evaluate 0xA + 6 Writes the result 16 to standard output. (The default output radix is decimal. Use -h for hexadecimal.) Evaluate lines += 1 The Evaluate command increments the value of the Shell variable {lines} by 1. If {lines} was undefined before executing the command, {lines} would be 1 after execution. ( Evaluate "{aPathname}" =~ /(([¬:]+:)*)®1≈/ ) > Dev:Null Echo {®1} These commands examine a pathname contained in the variable {aPathname} and return the directory prefix portion of the name. In this case, Evaluate is used for its side effect of enabling regular expression processing of a filename pattern. The right side of the expression ( /(([¬:]+:)*)®1≈/ ) is a regular expression that matches everything in a pathname up to the last colon and remembers it as the Shell variable {®1}. Evaluate’s actual output is not of interest, so it’s redirected to the bit bucket, Dev:Null. (See "Pseudo-Filenames" in Chapter 5.) Note that the use of I/O redirection means that the Evaluate command must be enclosed in parentheses so that the output redirection symbol, >, is not taken as an expression operator. This is a complex but useful example of implementing a "substring" function. For a similar example, see the Rename command. See also "Structured Commands" in Chapter 5. "Pattern Matching (Using Regular Expressions)" in Chapter 6, and Appendix B. æKY Execute æC Execute -- execute command file in the current scope Execute commandFile Execute returns the status returned by script. Description Executes the script as if its contents appeared in place of the Execute command. This means that variable definitions, exports, and aliases in the script will continue to exist after it has finished executing. (Normally these definitions, exports, and aliases would be local to the script.) Any parameters following script are ignored. Any parameters to the enclosing script are available within script. • Note: If script is not a command file (that is, if it’s a built-in command, tool, or application), the command is run as if the word Execute did not appear. Parameters are passed to the command as usual. Examples Execute {ShellDirectory}Startup Executes the Startup (and UserStartup) scripts. This command is useful for testing any changes you’ve made to the Startup-UserStartup script. Variable definitions, exports, and aliases set in Startup and UserStartup will be available after Startup is done executing. See also "Defining and Redefining Variables" in Chapter 5. "The Startup and UserStartup Files" in Chapter 5. æKY Exists æC Exists -- confirm the existence of a file or directory Exists [-d | -f | -w] [-q] name… > file -d # check if name is a directory -f # check if name is a file -w # check if name is a file and writeable -q # don't quote file names with special characters Status codes returned: 0 No error. 1 Syntax error. 2 Other error. Description Determines the existence of the file or directory name. The options help you to distinguish between directories and files and different access permissions. The nonexistence of name is not considered an error (status remains zero). Examples If Not "`Exists -d HD:dir`" NewFolder HD:dir End Duplicate ≈.c HD:dir This example creates a new directory and copies all files ending with ".c" in the current directory to this new directory. See also Newer command. æKY Exit æC Exit -- exit from a command file Exit [status] [If expression] If status is present, it is returned as the status value of the script. If the expression is invalid, –5 is returned. Otherwise, the status of the last command executed is returned. Description If the expression is nonzero (that is, true), Exit terminates execution of the script in which it appears. When used interactively, Exit terminates execution of previously entered commands. Status is a number; if present, it is returned as the status value of the script. Otherwise, the status of the previous command is returned. If the "If expression" is omitted, the Exit is unconditional. (For a definition of expression, refer to the description of the Evaluate command.) Examples Exit {ExitStatus} As the last line of a script, this Exit command would return as a status value whatever value had previously been assigned to {ExitStatus}. See also Evaluate command (for information on expressions). "Structured Commands" in Chapter 5. {Exit} and {Status} variables, in "Variables," Chapter 5. æKY Export æC Export -- make variables available to commands Export [-r | -s | name…] > exports -r # generate Unexport commands for all exported variables -s # print the names only Status codes returned: 0 No errors. 1 Syntax error. Description Make the specified variables available to scripts and tools. The list of variables exported within a script is local to that script. An enclosed script or tool inherits a list of exported variables from the enclosing script . (See Figure 5-1 in Chapter 5 of the MPW manual for clarification.) • Note: You can make a variable available to all scripts and tools by setting and exporting it in the Startup or UserStartup files. (Startup acts as the enclosing script for all Shell operations.) If no names are specified, a list of exported variables is written to standard output. (Note that the default output of Export is in the form of Export commands.) Examples Set AIncludes {MPW}Interfaces:AIncludes: Export AIncludes Defines the variable {AIncludes} as the pathname {MPW}Interfaces:AIncludes: and makes it available to scripts and programs. See also Unexport, Set, and Execute commands. "The Startup and UserStartup Files" in Chapter 5. "Exporting Variables" in Chapter 5. æKY FileDiv æC FileDiv -- divide a file into several smaller files FileDiv [option…] file [prefix] ≥ progress -b # input is a byte stream instead of lines -f # split file at formfeed character -n splitPoint # split file after splitPoint lines or bytes (-b) -p # write progress information to diagnostics -s n # set -b input buffer to n * 512 bytes Status codes returned: 0 Normal termination. 1 Parameter or option error. Description FileDiv is the inverse of the Catenate command. It is used to break a large file into several smaller pieces. The input file is divided into smaller files, each containing an equal number of lines determined by the splitpoint (default=2000). The last file contains whatever is left over. There is also an option (-f) for splitting a file only when a form feed character (ASCII $0C) occurs as the first character of a line that is beyond the splitpoint. This option lets you split a file at points that are known to be the tops of pages. Each group of splitpoint lines is written to a file with the name prefixNN, where NN is a number starting at 01. If the prefix is omitted, the input file name is used as the prefix. Examples FileDiv -f -n 2500 Bigfile Splits Bigfile into files of at least 2500 lines; splits the file at points where there are form feed characters. The output files have the names BigfileNN, where NN is 01, 02, and so on. Limitation The maximum length of an input line is 255 characters. æKY Files æC Files -- list files and directories Files [option…] [name…] > fileList -c creator # list only files with this creator -d # list only directories -f # list full pathnames -i # treat all arguments as files -l # long format (type, creator, size, dates, etc.) -m columns # n column format, where n = columns -n # don't print header in long or extended format -o # omit directory headers -q # don't quote filenames with special characters -r # recursively list subdirectories -s # suppress the listing of directories -t type # list only files of this type -x format # extended format with the fields specified by format Note: The following characters can specify the format a Flag attributes b Logical size, in bytes, of the data fork r Logical size, in bytes, of the resource fork c Creator of File ("Fldr" for folders) d Creation date k Physical size in kilobytes of both forks m Modification date t Type o Owner (only for folders on a file server) g Group (only for folders on a file server) p Privileges (only for folders on a file server) Status codes returned: 0 All names were processed successfully. 1 Syntax error. 2 An error occurred. Description For each disk or directory named, Files lists its contents; for each file named, Files writes its name and any other information requested. Information is written to standard output. When a directory is listed, all subdirectories are listed first in alphabetical order, followed by all files in alphabetical order. If no name is given, the current directory is listed. Examples files -r -s -f HD:source:defs.h HD:source:main.c HD:source:backup:main.c HD:source:backup:defs.h HD:source:junk:tmpfile Recursively lists the contents of the current directory, giving full pathnames and suppressing the printing of directory names. files -d :backup: :junk: Lists only the directories in the current directory. Files -i -x kd {AIncludes} Name Size Creation-Date --------------------------- ------ ---------------- HD:MPW:Interfaces:AIncludes: 365K 8/25/87 5:32 AM Lists the size and creation date of the {AIncludes} directory. Notice how the -i option is used to avoid printing the contents of the directory. files -m 2 :backup: deFs.h :junk: main.c This is the two-column format. Notice the order of the files. æKY Find æC Find -- find and select a text pattern Find [-c count] selection [window] -c count # find the nth selection, where n = count Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Any other error. Description Creates a selection in window. If no window is specified, the target window (the second window from the front) is assumed. It’s an error to specify a window that doesn’t exist. Selection is a selection as defined in Chapter 6 and in Appendix B of the MPW manual. • Note: Searches do not necessarily start at the beginning of a window. A forward search begins at the end of the current selection and continues to the end of the document. A backward search begins at the start of the current selection and continues to the beginning of the document. All searches are not case sensitive by default. You can specify case-sensitive searches by first setting the Shell variable {CaseSensitive} to a nonzero value. (Or, you can automatically set {CaseSensitive} by checking Case Sensitive in the dialog boxes displayed by the Find and Replace menu items.) Examples Find • Positions the insertion point at the beginning of the target window. Find -c 5 /procedure/ Sample.p Selects the fifth occurrence of "procedure" in the window Sample.p. Find 332 Selects line 332 in the target window. See also "Selections" and "Pattern Matching" in Chapter 6, and Appendix B. "Find Menu" in Chapter 3. æKY Flush æC Flush -- flush the tools that the Shell has cached Flush \. Status codes returned: 0 No errors always returned. Description Flush clears the MPW Shell's tool cache. The MPW Shell keeps the most recently used tools in memory so that execution can be faster. However, there are times when you don’t want the tools to be in the cache. For example, you cannot run a tool, and then switch to the Finder and delete the file. The Finder will report that the tool is busy. You might also want to flush the cache is when you are running benchmarks or timing tool performance. Examples Flush Flush the current cache. This will free all tools in the cache. æKY For æC For -- repeat commands once per parameter For name In word… command… End Status codes returned: 0 The list of words or list of commands was empty. –3 There was an error in the parameters to For. Description Executes the list of commands once for each word from the "In word…" list. The current word is assigned to variable name, and you can therefore reference it in the list of commands by using the notation {name}. You must end each line with either a return character (as shown above) or with a semicolon (;). The Break command can be used to terminate the loop. The Continue command can be used to terminate the current iteration of the loop. The pipe specification (|), conditional command terminators (&& and ||), and input/output specifications (<, >, >>, ≥, ≥≥, ∑, and ∑∑) may appear following the End; they apply to all of the commands in the list. Examples For i In 1 2 3 Echo i = {i} End Returns the following: i = 1 i = 2 i = 3 For File In ≈.c C {File} ; Echo {File} compiled. End This example compiles every file in the current directory whose name ends with the suffix ".c". The Shell first expands the filename pattern ≈.c, creating a list of the filenames after the "In" word. The enclosed commands are then executed once for each name in the list. Each time the loop is executed, the variable {File} represents the current word in the list. {File} is quoted because a filename could contain spaces or other special characters. For file in Startup UserStartup Suspend Resume Quit Entab {file} > temp Rename -y temp {file} Print -h {file} Echo {file} End This example entabs (replaces multiple spaces with tabs) the five files listed, prints them with headings, and echoes the name of each file after printing is complete. You might want to use this set of commands before making copies of the files to give to a friend. Entabbing the files saves considerable disk space, and printing them gives you some quick documentation to go with the files. See also Loop, Break, and Continue commands. "Structured Commands" in Chapter 5. æKY Format æC Format -- set or display formatting options for a window Format [[-f font] [-s fontsize] [-t tabsize] [-a attr]] | [-x fmt] [window…] -f fontName # set font to fontName -s fontSize # set the font size to fontSize -t tabSize # set the tab size to tabSize -a attr # set the auto indent and show invisibles flags -x fmt # output the current format in the specified format Note: The following attributes may be used with the -a option: A auto indentation on a auto indentation off I show invisibles on i show invisibles off L lock auto scrolling l unlock auto scrolling Note: The following characters may be used with the -x option: f font name s font size t tab size a attributes Status codes returned: 0 No errors. 1 Syntax error (error in parameters). 2 All other errors. Description This is a scriptable form of the Format menu command in the Edit menu. Use it to set the format of a specified list of windows. If no window is specified, the command operates on the target window. If no options are specified (other than -x), the current format settings are written to standard output. • Note: The Format command (and the Format menu command) modify the format of an existing window. The format related variables such as {Tab} and {Font} are used to initialize the format of a new window. Examples Format -f Monaco -t 8 -a A {target} Sets the font, tab size, and auto-indent in the target window. The font size and invisible settings are not changed. Format -s 12 MyWindow Changes the font size in MyWindow to 12 point. Format {Target} A format statement with no options displays the current format of the window, such as the following: Format -f Monaco -s 9 -t 8 -a Ai You can then select and execute this output format. Format -x tsf 4 9 Monaco Displays only the values of the specified options. Use this option for easily retrieving one or two values and assigning them to Shell variables for later use. See also The "Edit Menu," in Chapter 3. "Variables" in Chapter 5. æKY Get æC Get -- get a record from an indexed file Get (dataFile… | -dfl listfFle) [-k key] [-width w] [-d default key] [-h | -h2] [-l] [-m] [-nf] [-q] [-s] [-x] [-search] [-t] [-sfl] [-y] [-field field list] [-format format string] ] [-lessFields field list] dataFile # A specially formatted help file which must be # accompanied by an index file whose name is of # the form: dataFile.index, and and whose type is 'btre' -dfl listFile # listFile contains a list of datafiles -k keyword # keyword in the datafile's index file -width w # column format for key lists, w = 1..200 is the # window width in characters -d default # use default keyword if no keyword is specified -h # write full header -h2 # write short header (only the used datafile) -l # list all keys in the first data file that begin # with nnn, where nnn is the keyword following -k -lessFields tag [,tag]… # remove the named items from the existing field list # (default list or as specified by -field) -m # Select the keyword that was found and assign a marker to the selection -nf # no filtering; include field tags -q # quiet output when keyword not found -s # use the selection in the active window as keyword -x # create or update the cross reference index file -search # text search datafile for occurrences of keyword -t # write out template of the requested function/procedure -field tag[,tag]… # specify the data field(s) to display -format format_string # specify string(s) to be output in front of data # specified in -field option. '%s' flags in string # correspond ordinally to tags in -field option -sfl # produce ordered list of data files # (requires -dfl listFile) -y # do not present dialog before (re)building index file Status codes returned: 0 The search was successful 1 There was a syntax error 2 There was an error in processing 3 There was a system or out of memory error 4 The key was not found. -9 The user aborted the program Description Get searches the btree file dataFile.index looking for the key word key. If found, Get will return data associated with the key word from the file dataFile. The data may be formatted by columns. æKY GetErrorText æC GetErrorText -- display error messages based on message number GetErrorText [-f filename] [-s filename] [-n] [-p] errnbr[,insert,…] … GetErrorText -i idnbr,… # display error messages based on message number -f filename # explicit error msg file -i idnbr # report meaning of System Error Handler ID number -n # suppress error numbers in displayed messages -p # write SysErrs's version info to diagnostics -s filename # explicit system error msg file (default SysErrs.Err) Status codes returned: 0 Normal termination. 1 Parameter or option error. Description Displays the error messages corresponding to a set of specified error numbers or ID numbers. By default, GetErrorText assumes that the error numbers correspond to Macintosh Operating System error numbers. The file SysErrs.Err is a special file used by MPW tools to determine the error messages corresponding to system error numbers. Other system error message files may be specified by using the -s option. In addition to system errors, some tools have their own error message files. For example, the assembler's error message file is in the data resource fork of Asm itself. For such tools, you can display the error messages corresponding to tool error numbers by specifying the -f option. In this case, you can specify sample inserts, along with the error numbers, for error messages that take inserts, as shown above. GetErrorText can also display the meanings of the ID numbers reported by the System Error Handler in alert dialog boxes. The -i option is used for this purpose. Examples GetErrorText -43 -44 -45 Displays the error messages corresponding to system errors -43, -44, and -45. GetErrorText -i 28 2 Displays the error messages corresponding to system ID numbers 28 and 2. æKY GetFileName æC GetFileName -- display a Standard File dialog box GetFileName [-q] [-s] [-c | [[-t TYPE]… | -p | -d | -wd] [-m message] [-b buttontitle] [pathname]] -b buttontitle # specify the default button's title -c # write current standard file path to standard output -d # select a directory -wd # select a directory on a non-locked volume -m message # specify a prompt -p # select a new filename (SFPutFile) -q # suppress quoting of filenames -s # return 0 status even if cancel is clicked -t type # specify file type for SFGetFile dialog Status codes returned: 0 User specified a file and no errors occurred. 1 Parameter or option error. 2 System error. 4 User canceled the standard file dialog box. Description GetFileName displays a standard file dialog box. Either SFPutFile or SFGetFile is called, and the returned filename or pathname is written to standard output. The standard file starting directory is set to pathname if specified. If pathname includes a local filename and if SFPutFile is called, the local filename is used as the default filename. See the examples. Examples Open `GetFileName -t TEXT {pinterfaces}` Opens the text file in directory {pinterfaces} chosen in SFGetFile by the user. GetFileName -p HD:MPW:StartUp An SFPutFile dialog box is displayed with the directory set to HD:MPW: and StartUp is displayed in the textedit field of the dialog box. Limitation The resulting filename cannot be longer than 255 characters. See also "The Standard File Package," Inside Macintosh, Volume I. æKY GetListItem æC GetListItem -- display items for selection in a dialog box GetListItem [option…] [[item…] | < file] -c[ancel] # return a status of 0 even when cancel is clicked -d[efault] item # item is entered in list and comes up selected -m[essage] message # display message in dialog above the list -q[uote] # don't quote items in the output -r[ows] rows # make the list with this many rows -s[ingle] # only allow a single selection -sort # sort input list -w[idth] width # make the list this many pixels wide Status codes returned: 0 No errors (or Cancel button was clicked if -c option is used). 1 Syntax error (bad option). 2 Cancel button was clicked. Description Takes the items on the command line (or, if no items are present on the command line, items from standard input) and lists them in a dialog box. Items in the list can be selected with the mouse and modifier keys. Selected items are written to standard output when the OK button is clicked. Examples Print `files -t TEXT | GetListItem -m "Select files to print:"` Lists all text files in the current directory and prints those selected by the user, as shown below. æKY Help.MPW æC Help -- write summary information Help [-f helpfile] [command…] > helpInformation -f helpfile # alternate helpfile (default MPW.Help) Status codes returned: 0 Information was found for the given command. 1 Syntax error. 2 A command could not be found. 3 The help file could not be opened. æKY If æC If -- conditional command execution If expression command… [Else If expression command… ] … [Else command… ] End Status codes returned: 0 None of the lists of commands were executed. –1 Invalid expression. Description Executes the list of commands following the first expression whose value is nonzero. (Null strings are considered zero.) At most one list of commands is executed. You may specify any number of "Else If" clauses. The final Else clause is optional. The return characters (as shown above) or semicolons must appear at the end of each line. The pipe specification (|), conditional command terminators (&& and ||), and input/output specifications (<, >, >>, ≥, ≥≥, ∑, ∑∑) may appear following the End and apply to all of the commands in the list. For a definition of expression, see the description of the Evaluate command. Examples If {Status} == 0 Beep 1a,25,200 Else Beep -3a,25,200 End Produces an audible indication of the success or failure of the preceding command. For window in `Windows` If {window} != {Worksheet} AND {window} != {Active} Close {window} End End Closes all of the open windows except the active window and the Worksheet window. (Refer also to the Windows command.) The following commands, as a script, would implement a trivial case of a general "compile" command: If {1} =~ /≈.c/ C {COptions} {1} Else If {1} =~ /≈.p/ Pascal {POptions} {1} End If the above commands were saved in a file (say, as "Compile"), both C and Pascal programs could be compiled with the command Compile filename See also Evaluate command (for a description of expressions). "Structured Commands" in Chapter 5. æKY Lib æC Lib -- combine object files into a library file Lib [option…] objectFile… ≥ progress -d # suppress duplicate definition warnings -df deleteFile # delete modules listed in file deleteFile -dm name[,name]… # delete external modules and entry points -dn name[,name]… # delete external names, making them local -f # allow FORTRAN-style common data -mf # use MultiFinder temporary memory if necessary -o name # write object file name (default Lib.Out.o) -p # write progress information to diagnostics -rn OldNameA=NewNameA # change module name(s) OldNameA to NewNameA, [,OldNameB=NewNameB]… # OldNameB to NewNameB, etc. -sg newSeg=old[,old]… # merge old segments into new segment -sn oldSeg=newSeg # change segment name oldSeg to newSeg -sym [On | Full] # keep symbolic information (default) [Off] # discard symbolic information, can be followed by: [,NoLabels] # discard label information [,NoLines] # discard source line information [,NoTypes] # discard type information [,NoVars] # discard variable information -ver N # set OMF file version number to N -w # suppress warnings Status codes returned: 0 No problem. 1 Syntax error. 2 Fatal error. Description Combines the specified object files into a single file. Input files must have type 'OBJ' . Lib is used for the following: • Combining object code from different languages into a single file. • Combining several object files into a larger object file (a library). • Combining several libraries into a single library, for use in building a particular application or desk accessory. This can greatly improve the performance of the Linker. • Deleting unneeded modules (with the -dm option), changing segmentation (the -sg and -sn options), or changing the scope of a symbol from external to local (the -dn option). (These options are useful when you construct a specialized library for linking a particular program.) Object files that have been processed with Lib result in significantly faster links when compared with the "raw" object files produced by the assembler or compilers. The output of Lib is logically equivalent to the concatenation of the input files, except for the optional renaming, resegmentation, and deletion operations, and the possibility of overriding an external name. The resolution of external names in Lib is identical to Link—in fact, the two programs share the same code for reading object files. Although multiple symbols are reduced to a single symbol, no combining of modules into larger modules is performed, and no cross-module references are resolved. This behavior guarantees that the Linker’s output will be the same size whether or not the output of Lib was used. See "Library Construction" in Chapter 10 of the MPW manual for a detailed discussion of the behavior and use of Lib. Examples Lib {CLibraries}≈ -o {CLibraries}CLibrary.o Combines all of the library object files from the {CLibraries} directory into a single library named CLibrary.o. For applications that require most or all of the C library files, using the new CLibrary file will reduce link time. See also Link, DumpObj, and DumpCode commands. "Optimizing Your Links" and "Library Construction" in Chapter 10. Appendix H. æKY Line æC Line -- find line in the target window Line n Status codes can be returned by either the Find or the Open commands that make up the Line script: 0 No errors. 1 Syntax error. 2 No target window; other error. 3 System error. Description Line finds line n in the target window. The parameter n is usually an integer, but may be any selection expression. The target window becomes the active (frontmost) window. Line is a script containing these two commands: Find {1} {target} # Find line n in the target window Open {target} # Bring the target window to the top Examples Line 123 Finds line 123 in the target window and makes the target window the new active window. ### Undefined symbol: length File Count.c; Line 75 The File and Line commands above are part of an error message produced by the MPW C compiler. The MPW Assembler and MPW Pascal compilers produce errors when using similar formats. You can execute such error messages to find the line that contains the error. The command File is defined as an alias for Target in the Startup file. Thus File opens the specified file as the target window. Line then selects the offending line in the window and brings the window to the front. Notice that the remainder of the error message is a comment. See also Find command. æKY Link æC Link -- link an application, tool, or resource Link [option…] objectFile… > map ≥ progress -ac alignment # align code modules to 'n' byte boundaries -ad alignment # align data modules to 'n' byte boundaries -c creator # set resourceFile creator (default ????) -d # suppress duplicate definition warnings -da # desk accessory - add NULL to segment names -f # allow FORTRAN-style common data -l # write a location map to output -la # -l, include anonymous symbols in location map -lf # -l, include file and location of definitions -m mainEntry # use mainEntry as main entry point -ma name=alias # create an alias for module name -map # generate "friendly" link map -mf # use MultiFinder temporary memory if necessary -model far # process 32-bit load-time relocatable references -model near # prohibit 32-bit load-time relocatable references -msg keyword[,…] # message options [no]dup # (suppress) warnings about duplicate symbols [no]multiple # (suppress) multiple undefined symbol reports [no]warn # (suppress) warning messages -o resourceFile # write resourceFile (default Link.Out) -opt [Off] # disable Object Pascal optimizations (default) [On ] # enable optimizations [NoBypass] # enable optimizations, but always dispatch [,Info] # write optimization information to diagnostics [,Names] # include MacsBug symbols within SelectorProc modules -p # write progress information to diagnostics -pg size # set page size to "size"; max:32K; min: 1024; default: 2048 -ra [seg]=attr[,attr…] # set segment resource attributes: $xx (or) nnn # a hex or decimal attribute you figure out resSysHeap # or a comma-seperated list of resource resPurgeable # attributes by name resLocked # resProtected # resPreload # resChanged # (essentially ignored) -rn # don't include resource names in resourceFile -rt type[=id] # set resource type and lowest id (default CODE=0) -sg newSeg[=old[,old]…] # merge old segments into new segment -sn oldSeg=newSeg # change segment name oldSeg to newSeg -srt # sort global data by "near" and "far" references -ss size # maximum segment size (default 32760) -sym [Off] # disable symbolic output (default) [On | Full] # enable symbolic output, can be followed by: [,NoLabels] # omit label information [,NoLines] # omit source line information [,NoTypes] # omit type information [,NoVars] # omit variable information -t type # set resourceFile type (default APPL) -uf unrefFile # write list of unreferenced modules to unrefFile -w # suppress warnings -wrap # when jump table space is exhausted, put excess jump table # entries in global data space, if available -x crossRefFile # write cross reference to crossRefFile Status codes returned: 0 No problem. 1 Syntax error. 2 Fatal error. Description Links the specified object files into an application, tool, desk accessory, or driver. The input object files must have type 'OBJ'. Linked segments from the input object files are placed in code resources in the resource fork of the output file. The default output filename is Link.Out, but you can specify other names with the -o option. For detailed information about the linker, and instructions for linking applications, MPW tools, and desk accessories, see Chapters 8 and 10 of the MPW manual. The first dialog box of Link’s Commando dialog is reprinted here for convenience. The linker’s default action is to link an application, placing the output segments into 'CODE' resources. When you link an application, all old 'CODE' resources are deleted before the new 'CODE' resources are written. By default, resources created by the linker are given resource names that are the same as the corresponding segment names. You can change a resource (segment) name with the -sn or -sg options, and you can create unnamed resources with the -rn option. The linker executes in four phases: • Input phase: The linker reads all input files, finds all symbolic references and their corresponding definitions, and constructs a reference graph. Duplicate references are found and warnings are issued. • Analysis phase: The linker allocates and relocates code and data, detects missing references, and builds the jump table. If the -l or -x option is given, Link produces a linker map or cross-reference listing. The linker also eliminates unused code and data. • Output phase: The linker copies linked code segments into code resources in the resource fork of the output file. By default, these resources are given the same names as the corresponding segment names. (The cursor spins backward during this phase.) • Symbolic output phase: Optionally, Link may be used to create the .SYM file for use with SADE. Examples Link Sample.p.o ∂ "{PLibraries}"PInterface.o ∂ "{PLibraries}"PasLib.o ∂ "{Libraries}"Runtime.o ∂ -o Sample ∂ -la >Sample.map Links the main program file Sample.p.o with the libraries PInterface.o, PasLib.o, and Runtime.o, placing the output in Sample and placing the Linker map in the file Sample.map. Sample is an application that can be launched from the Finder or executed from MPW. Link -rt MROM=8 -c 'MPS ' -t ZROM -ss 140000 ∂ -l > ROMLocListing -o MyROMImage {LinkList} Links the files defined in the Shell variable {LinkList} into a ROM image file, placing the output in the file MyROMImage. The segment size is set to 140,000 bytes, and the ROM is created as a resource 'MROM' with ID=8. The file is typed as being created by MPW (creator 'MPS '), with file type ZROM. Link’s location-ordered listing is placed in the file ROMLocListing. For additional examples, see "Link" in Chapter 10 and the makefiles in the Examples folders for the languages you are using. See also Lib command and Appendix H, "Object File Format." Chapter 8, "The Build Process," and Chapter 10, "Link." The Segment Loader and the Resource Manager chapters in Inside Macintosh. Inside Macintosh, Volume IV, for information on the 128K ROM, the System Folder, and the Finder. æKY Loop æC Loop -- repeat commands until Break Loop command… End Loop returns the status of the last command executed. Description Executes the enclosed commands repeatedly. The Break command is used to terminate the loop. The Continue command can be used to terminate the current iteration of the loop. The pipe specification (|), conditional command terminators (&& and ||), and input/output specifications (<, >, >>, ≥, ≥≥, ∑, and ∑∑) may appear following the End, and apply to all of the commands in the list. Examples The following script runs a command several times, once for each parameter: ### Repeat - Repeat a command for several parameters ### # Syntax: # Repeat command parameter… # # Execute command once for each parameter in the parameter # list. Options can be specified by including them with # the command name in quotes. # Set cmd {1} Loop Shift Break If {1} == {cmd} {1} End Notice that Shift is used to step through the parameters, and that Break ends the loop when all parameters have been used. See also Break, For, and Continue commands. "Structured Commands" in Chapter 5. æKY Make æC Make -- build up-to-date version of a program Make [option…] target… > commands ≥ progress -d name[=value] # define variable name as value (overrides makefile) -e # rebuild everything regardless of dates -f makefile # read dependencies from makefile (default MakeFile) -p # write progress information to diagnostics -r # write roots of dependency graph to output -s # write structure of target dependencies to output -t # touch dates of targets and prerequisites -u # identify targets in makefile not reached in build -v # write verbose explanations to diagnostics -w # suppress warnings -y # like -v, but omit announcing up-to-date targets Status codes returned: 0 Successful completion. 1 Parameter or option error. 2 Execution error. Description Generates a set of Shell commands that you can execute to build up-to-date versions of the specified target files. (If no target is specified, the target on the left side of the first dependency rule in the makefile is built.) Make allows you to rebuild only those components of a program that require rebuilding. Make determines which components need rebuilding by reading a makefile. This is a text file that describes dependencies between the components of a program, along with the Shell commands needed to rebuild each component. You can specify makefiles with the -f option. After processing the makefiles, Make writes to standard output the appropriate set(s) of commands needed to rebuild the target(s). See "Format of a Makefile" in Chapter 9 of the MPW manual for a description of the format of a makefile. The first dialog box of Make’s Commando dialog is reproduced here for convenience. Make executes in two phases: • In the first phase, Make reads the makefile(s) and creates a file (target) dependency graph. (The "beachball" cursor spins counterclockwise during this phase.) • In the second phase, Make generates the build commands for the target to be built (the cursor spins clockwise). If a target file doesn’t exist or if it depends on files that are out-of-date or newer than the target, Make writes out the appropriate command lines for updating the target file. This process is recursive and "bottom up" so that commands are issued first for those lower-level dependencies that need to be rebuilt. You can execute the generated build commands after Make is done executing. Examples Make -p -f MakeFile Sample Makes the target file Sample, and prints progress information. Sample’s dependency relations are described in the makefile :AExamples:MakeFile. Sample ƒƒ Sample.r Rez Sample.r -o Sample -a SetFile -a B Sample -c ASMP -t APPL #set bundle bit Sample ƒƒ Sample.r Sample.a.o Link Sample.a.o -o Sample Sample.a.o ƒ Sample.a Asm Sample.a The ƒ (Option-F) character means "is a function of"—that is, the file on the left side depends on the files on the right side. If the files on the right are newer, the subsequent Shell commands are written to standard output. (See Chapter 9 for details.) See also "Format of a Makefile" in Chapter 9 for the format of a makefile, examples, and other information about using Make. Makefiles for building sample programs are contained in the Examples folders: • Examples:AExamples:Makefile • Examples:PExamples:Makefile • Examples:CExamples:Makefile æKY MakeErrorFile æC MakeErrorFile -- create error message textfile MakeErrorFile [option…] [file…] < file > listing ≥ progress -l # write listing to standard output -o file/dir # output file or directory -p # write progress information to diagnostics Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. Description MakeErrorFile creates specially formatted error message files used to retrieve the error messages associated with error numbers. The ErrMgr unit in the ToolLibs.o library is used by programs to access the error files created by MakeErrorFile. SysErrs.Err is one such error file; it is used by various MPW tools to get the textual messages associated with Macintosh system error codes. See the documentation on the ErrMgr unit for more information on how error files are accessed. Examples MakeErrorFile SysErrs -l >SysErrsList Writes an ordered list of system error numbers and messages to the file SysErrsList. æKY Mark æC Mark -- assign a marker to a selection Mark [-y | -n] selection name [window] -y # replace existing marker (avoids dialog) -n # don't replace existing marker (avoids dialog) Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Mark assigns the marker name to the range of text specified by the selection in window. If no window is specified, the command operates on the target window (the second window from the front). The new marker name is included in the Mark menu when window is the current active window. A marker is associated with a logical, as opposed to absolute, range of text. The ranges of markers may overlap, but each marker must have a unique name. Marker names are case sensitive. A dialog box requests confirmation if the marker name conflicts with an existing marker name. The -y or -n option can be used in scripts to avoid this interaction. Deletion and insertion operations affect markers according to these rules: • Any editing outside the range of a marker will not affect the logical range of the marker, where "outside" means that the range of editing changes does not intersect the range of the marker. • Any editing inside the range of a marker will change the logical range of the marker by the amount of the editing change. For example, adding ten characters to the inside of a marker’s range will increase the range of the marker by ten characters. Another way to say this is that a marker has responsibility for all the characters added to (or deleted from) its range. • Any deletion that totally encloses a marker will delete the marker. Examples Mark § 'Procedure 1' Assigns a marker with the name "Procedure 1" to the current selection in the target window. Limitation It is currently not possible to "Undo" the effects of any editing operations on markers. See also Unmark and Markers commands. "Mark Menu" in Chapter 3. "Markers" in Chapter 6. æKY Markers æC Markers -- list markers Markers [-q] [window] -q # don't quote the marker names Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Markers prints the names of all markers associated with window. The names are written one per line, and they are ordered from the beginning to the end of the window. Examples Markers {Target} Lists all markers associated with the target window. See also "Mark Menu" in Chapter 3. "Markers" in Chapter 6. æKY MatchIt æC MatchIt -- semi-intelligent language sensitive bracket matcher MatchIt [-a[sm] | -p[ascal] | -c] [-h] [-l] [-n] [-v] [window] -a[sm] # target language is Assembler -p[ascal] # target language is Pascal -c # target language is C -h # highlight all characters enclosed by match -l # highlight entire lines containing match -n # generate error message if no match -v # display MatchIt's version number Status codes returned: 0 Normal termination. 1 Parameter or option error. 3 Matching delimiter not found (only if -n option specified). Description Matches C, Pascal, and assembly-language delimiters with their mates in the specified window. The default window is the target window (second from front). The characters highlighted as the current selection1 in the window are used as the left delimiter. MatchIt attempts to find the corresponding right mate for the selected delimiter. MatchIt is syntax sensitive, so that it is semi-intelligent about how it finds the matching delimiter. For example, if a Pascal BEGIN is the specified selection, MatchIt finds the proper END that matches it. All commenting conventions, strings, nesting, and so on are taken into account when searching for the end delimiter. The functionality of MatchIt is similar to the Shell editor’s ability to find mates for the characters ( [ { and '' when you double-click any of these characters. However, MatchIt differs from the Shell editor by supporting even more delimiters and using the knowledge of the target language syntax to find the proper match. The following table summarizes all the delimiters supported and for which languages: Examples matchit mysource.p For the current selected delimiter in the open window mysource.p, find the delimiter's mate. The language is assumed to be Pascal (because of the .p suffix.). No message is reported and the selection is not changed if the mate cannot be found. Of course, errors are still reported to diagnostic output if the input selection is not a valid Pascal delimiter (according to the table in "Options"). If MatchIt is to be used explicitly, a more general form for its use is shown in this example: matchit -n "{target}" For the current selected delimiter in the open target window, find the delimiter’s mate. The "{target}" specification could have been omitted, as it is MatchIt’s default. If explicitly specified, as shown here, it is best to quote it. The language is determined by the window’s name suffix (if present), or by the the selection, if the suffix is not acceptable to MatchIt. An error is reported if the mate cannot be found (-n). While the second example is more general than the first, and either might be useful for Shell scripts (particularly when the -n option is used), the real use for MatchIt is as a generalization of the the Shell editor’s own double-clicking delimiter matching mechanism. The following example illustrates this purpose: addmenu Edit 'Match It/µ' 'matchit -n -h ∂ "{active}" ≥ "{MPW}"Errors || ∂ alert < "{MPW}"Errors' This example places a MatchIt call into the Edit menu as the command Match It with a command key Option-m (the µ). A selection is made in the current (that is, the {active}) window and the menu command invoked (by pressing Command-Option-m). If the match is found, all characters from the initially selected delimiter to its mate are highlighted (-h). If a match is not found, or if any other errors occur, an alert dialog box appears containing the error message. An auxiliary file, "{MPW}"Errors, is used for this purpose. Of course, you might not be interested in displaying the dialog box because you can see that the selection doesn’t change if there are any errors. Furthermore, you might not want superfluous files laying around ("{MPW}"Errors—although you could create a more elaborate AddMenu command to always delete this file). Thus, you could make the following simplification: addmenu Edit 'Match It/µ' 'matchit -h "{active}" ≥ dev:null' This example places a MatchIt call into the Edit menu but with all errors ignored when the MatchIt command is executed. Limitations MatchIt does not process conditionals (that is, Pascal $ifc, C #if, and so on) during its scan except to find matching pairs. This might confuse MatchIt’s scanning process. Similarily, C macros and "\" continuations may also confuse MatchIt. MatchIt only finds a right delimiter to the specified left delimiter. Right-to-left matching is not supported. æKY MergeBranch æC MergeBranch -- merge a branch revision onto the trunk MergeBranch file… Status codes returned: 0 No Errors. 1 Syntax Error. 2 Error in Processing. 3 System Error. Description Merge the branch revision of the HFS file file onto the trunk. The file must belong to a currently mounted project and must be a branch revision (that is, the revision number contains one or more letters). MergeBranch uses the ProjectInfo command to determine what project file belongs to and whether file is in fact a branch revision. If all of the file's revisions are older than the branch, the branch will be checked in as the latest trunk revision. Otherwise MergeBranch checks out the latest revision on the trunk and calls CompareFiles to allow the user to manually cut and paste changes from the branch into the trunk revision. When done, the user can check the modified trunk revision back into the project. MergeBranch uses the CompareFiles script. Examples MergeBranch file.c This example merges the branch revision in the file "file.c" onto the trunk. AddMenu Project 'Merge Branch' 'Merge Branch {Active} ∑∑ {WorkSheet}' This example adds MergeBranch to the Project menu and allows you to merge branch revisions onto the trunk. See also CompareFiles. æKY ModifyReadOnly æC ModifyReadOnly -- enables a read-only Projector file to be edited ModifyReadOnly file … Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. Description Write-enable a file that has been checked out as read-only. After executing this command on a file, the modified read-only icon is displayed in the window. This command is most useful on those rare occasions when you need to modify a read-only file. For example, suppose you have taken a number of modifiable files home. You may have also brought along certain read-only copies of files that you did not expect to modify, but once you get into your work at home you discover that you do, after all, need to make changes in these files. Note that this command takes only a single file for a parameter. This "feature" was intentional so that this command would not be overused. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples Suppose file.c is checked out as read-only. You can write-enable it by using the ModifyReadOnly command: ModifyReadOnly file.c ProjectInfo :file.c -s The ProjectInfo command writes the following to standard output: file.c,5* Notice that an asterisk appears after the revision number when you get information about modified read-only files. See also CheckIn, CheckOut, CheckOutDir. æKY Mount æC Mount -- mount volumes Mount drive… Status codes returned: 0 The disk was mounted. 1 Syntax error. 2 An error occurred. Description Mounts the disks in the specified drives, making them accessible to the file system. Drive is the drive number. Mounting is normally automatic when a disk is inserted. The Mount command is needed for mounting multiple hard disks, which cannot be "inserted," or for volumes that have been unmounted via the Unmount command. Examples Mount 1 Mounts the disk in drive 1 (the internal drive). See also Unmount and Volumes commands. æKY MountProject æC MountProject -- mount projects MountProject ([-s] [-pp] [-q] [-r]) | [Project] -s # print names only, not commands -pp # list mounted projects using project paths -q # don't quote names with special characters -r # list projects recursively Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description MountProject mounts (establishes a connection to) the specified project. Project is the HFS path of the project directory for the project. Once a project is mounted, that project and all its subprojects can be accessed. MountProject commands typically appear in the UserStartup file, a script, or an AddMenu to automatically mount the projects you typically access. If project is omitted, a list of all root projects is written to standard output in the form of MountProject commands. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples MountProject FS:Zoom MountProject HD:localProjects:Test These commands mount the projects Zoom and Test. MountProject MountProject FS:MPW MountProject HD:localProjects:sort To obtain a list of the current root projects, execute the MountProject command without parameters. See also UnmountProject, Project, CheckOutDir. æKY Move æC Move -- move files and directories Move [-y | -n | -c] [-p] name… target ≥ progress -y # overwrite target files (avoids dialog) -n # don't overwrite target files (avoids dialog) -c # cancel if conflict occurs (avoids dialog) -p # write progress information to diagnostics Status codes returned: 0 All objects were moved. 1 Syntax error. 2 An error occurred during the move. 4 Cancel was selected or implied with the -c option. Description Moves name to targetName. (Name and targetName are file or directory names.) If targetName is a directory, one or more objects (files and/or directories) are moved into that directory. If targetName is a file or doesn’t exist, file or directory name replaces targetName. In either case, the old objects are deleted. Moved objects retain their current creation and modification dates. If a directory is moved, its contents, including all subdirectories, are also moved. No directory moved can be a parent of targetName. A dialog box requests a confirmation if the move would overwrite an existing file or folder. The -y, -n, or -c option can be used to avoid this interaction. Examples Move Startup Suspend Resume Quit {SystemFolder} Moves the four files from the current directory to the System Folder. Move File :: Moves File from the current directory to the enclosing (parent) directory. Move -y File1 File2 Moves File1 to File2, overwriting File2 if it exists. (This is the same as renaming the file.) See also Duplicate and Rename commands. "File and Window Names" in Chapter 4. "Filename Generation" in Chapter 5. æKY MoveWindow æC MoveWindow -- move window to h,v location MoveWindow [h v] [-i] [window] h # horizontal position of top left corner v # vertical position of top left corner -i # ignore positioning errors Status codes returned: 0 No errors. 1 Syntax error (error in parameters). 2 The specified window does not exist. 3 The h v location specified is invalid. Description Moves the upper-left corner of the specified window to the location (h v), where h and v are horizontal and vertical integers, respectively. Use a space to separate the numbers h and v on the command line. The coordinates (0,0) are located at the left side of the screen at the bottom of the menu bar. If the location specified would place the window’s title bar entirely off the visible screen, an error is returned. (The -i option overrides the error.) If no window is specified, the target window (the second window from the front) is assumed. If no location is specified, the specified window’s location is returned without any effect on the window. Examples MoveWindow 72 72 Moves the target window’s upper-left corner to a point approximately one inch in from the upper-left corner of the screen, and one inch below the bottom of the menu bar. (There are about 72 pixels per inch on the Macintosh display screen.) MoveWindow Returns MoveWindow 72 72 when executed after the above example. MoveWindow 0 0 {Worksheet} Moves the Worksheet window to the upper-left corner of the screen (below the menu bar). See also SizeWindow, StackWindows, RotateWindows, TileWindows, and ZoomWindow commands. æKY NameRevisions æC NameRevisions -- define a symbolic name NameRevisions [-u User] [-project Project] [-public |private | -b] [-r] [[-only] | name [[-expand] [-s] | [-replace] [-dynamic] [names… | -a]]] -u user # name of current user -private # create a private name -project project # name of project that contains the revisions -public # create a public name -b # print both public and private names -expand # evaluate names to revision level before printing -only # only print the names, not the associated revisions -replace # completely overwrite the previous definition of name -dynamic # evaluate names to revision level when using not defining -r # recursively execute NameRevisions starting with current project -s # print a single name per line -a # all the files in the project Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Create a symbolic name to represent a set of revisions under Projector. Subsequently, when name is used in Projector commands, its value, names, is substituted in its place. Symbolic names are kept on a per-project basis and can be composed of filenames, revisions, branches, and other defined symbolic names. A symbolic name can include only one revision per file. The first character of a Name cannot be a digit (0–9). Also, commas, greater-than or less-than signs, (<, <, > >), or hyphens (-) are not allowed anywhere in a Name. Names are not case sensitive. If names is missing, the definition for name is listed. If name is missing, then NameRevisions lists all symbolic names in the project. In either case, the output is in the form of NameRevisions commands. By default, if names currently refers to a file listed in name, the revision for the file in name is modified to be the revision associated with the file in names. If there is a file in names which is not currently referred to by name, that file and revision is appended to name. To replace the definition of name, include the -replace option. The default is to create a private symbolic name. Include the -public option to make the symbolic name available to all users. You can add definitions for private symbolic names to UserStartup. Public symbolic name are stored with the project so they need to be defined only once. Do not put public symbolic name definitions in UserStartup. Projector checks for various errors both when a symbolic name is defined and when it is used. Errors include referring to a nonexistent file or referring to more than one revision in a file. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples Assuming the latest revisions of the files file.c and interactive.c are 9 and 13 respectively, the first example defines a symbolic name "Work" that always expands to the files file.c,9 and interactive.c,13. NameRevisions Work file.c interactive.c The following command: CheckOut Work Is equivalent to: CheckOut file.c,9 interactive.c,13 By omitting the Names parameter, the next NameRevisions command generates the current definition of Work. NameRevisions Work NameRevisions Work file.c,9 interactive.c,13 The -dynamic is an important option. The following two commands illustrate its function: NameRevisions fred file.c NameRevisions -dynamic fred file.c The first command defines a symbolic name "fred" that always expands to the latest revision of file.c when fred was defined. The second example expands to the latest revision at the time of use. If the latest revision of file.c at the time fred was defined was 7 and the current latest revision is 9, the second NameRevisions command is equivalent to NameRevisions fred file.c,9 The next command creates the symbolic name "file.c" that expands to the second revision off the first branch off the 1.1 revision of file.c. NameRevisions file.c file.c,1.1a2 The command CheckOut file.c checks out revision 1.1a2 of file.c. The next example creates a Name "file.c" that expands to the latest version of the first branch off the 1.1 revision of file.c. NameRevisions -dynamic file.c file.c,1.1a So the checkout command CheckOut file.c will check out the latest revision on the first branch off revision 1.1 of file.c. The next example defines all the latest revisions in the project Kerfroodi to be part of "v1.0 B1". Because this a global name, all users accessing the Kerfroodi project will be able to use the name "v1.0 B1". NameRevisions -public "vB1 1.0" -project Kerfroodi -a The name "BetaRelease" is defined recursively for all projects within the Zoom project: NameRevisions -project Zoom∫ -r "BetaRelease" -a Its behavior is the same as executing the following commands individually: NameRevisions -project Zoom "BetaRelease" -a NameRevisions -project Zoom∫Vroom "BetaRelease" -a NameRevisions -project Zoom∫Utilities "BetaRelease" -a NameRevisions -project Zoom∫Utilities∫Port "BetaRelease" -a ... See also ProjectInfo, DeleteNames. æKY New æC New -- open a new window New [name…] Status codes returned: 0 No errors. 1 Syntax error (error in parameters). 2 Unable to complete operation; a file with the specified name already exists. 3 System error. Description Opens a new window as the active (frontmost) window. If name is not specified, the Shell generates a unique name for the new window, of the form "Untitled-n", where n is a decimal number. If name already exists, an error results. You can use New to open several new windows by specifying a list of names separated by spaces. Note that New differs from Open -n by returning an error if the file already exists, whereas Open -n either opens an existing file or creates a new file. If the Shell variable {NewWindowRect} is defined, the windows are opened to that size and location. Examples New Opens a new window with a Shell-generated name. New Test.a Test.p Test.c Creates three windows called Test.a, Test.p, and Test.c. See also Open command. æKY Newer æC Newer -- compare modification dates of files Newer [-c] [-e] [-q] file… target > newer -c # compare creation dates -e # report names that have same (equal) mod date as target -q # don't quote file names with special characters Status codes returned: 0 No error. 1 Syntax error. 2 File not found. Description Compares the modification dates of name and target. Files that have a more recent modification date than target have their names written to standard output. If the target is a nonexistent file or directory, all names that exist are considered newer than the target. Examples Newer main.c main.c.bak Writes out main.c if its modification date is more recent than its backup. Newer HD:Source:≈.c HD:TimeStamp Writes to the screen all the source files in the Source directory that have been modified since the modification date of TimeStamp. If `Newer main.c main.c.bak` Duplicate main.c main.c.bak End Makes a backup copy of main.c only if it has been modified since the last backup was made. If "`Newer File.c File.h File.c.o`" C File.c -o file.c.o End Rebuilds the source file file.c if either file.c or file.h has been modified since file.c.o was last built. æKY NewFolder æC NewFolder -- create a new folder NewFolder name… Status codes returned: 0 Folders were created for each name listed. 1 Syntax error. 2 An error occurred. 3 Attempt to use NewFolder on a non-HFS volume. Description Creates new directories with the names specified. Any parent directories included in the name specification must already exist. • Note: This command can be used only on hierarchical file system (HFS) disks. Examples NewFolder Memos Creates Memos as a subdirectory of the current directory. NewFolder Parent :Parent:Kid Creates Parent as a subdirectory of the current directory, and Kid as a subdirectory of Parent. æKY NewProject æC NewProject -- create a new project NewProject -w | -close | ([-u user] [-cs comment | -cf file] project) -cf file # the comment is contained in file. -close # close the New Project window -cs comment # a short description of the project -w # open the New Project window -u user # name of current user Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description NewProject creates a project under control of Projector. A project directory is created to store the files, subprojects, and other information related to the project. The name of the directory is the name of the project. If project is a project pathname (such as MPW∫Tools∫Enterprise), Projector creates Enterprise as a subproject of the existing MPW∫Tools project. In this case MPW∫Tools must be a mounted project (see the MountProject command). If project is a leafname (such as Enterprise), project directory Enterprise is created in the current directory. Finally, if project is a partial or full HFS pathname (such as :Work:Enterprise or FS:Projects:Enterprise), the project Enterprise is created in the HFS location specified. Add a MountProject command to the UserStartup file, a script, or AddMenu to easily mount the new project. The checkout directory is initially set to the current directory (:). To change the checkout directory, refer to the CheckOutDir command. To add files to the new project, use the CheckIn command (with the -new option) or the Check In window. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples The following command creates a project Enterprise in the current directory. No comment is saved with the project, but you can add one later by selecting the project in the Check Out window's /Info view. NewProject Enterprise The next example creates a project Zoom in the FS:work:Zoom. The -cf option indicates that the comment for the new project is contained in the file Info. NewProject FS:work:Zoom -cf Info Finally, given that the project Enterprise∫Utilities exists and has been mounted using the MountProject command, the next command creates a Zoom project in the Enterprise∫Utilities project. In this case you don’t need to add a MountProject command to UserStartup, but you may want to add a CheckOutDir command to set the checkout directory. NewProject Enterprise∫Utilities∫Zoom -cs ∂ "Upgrade Zoom utility" See also CheckOutDir, MountProject, Project. æKY Open æC Open -- open file(s) in window(s) Open [-n | -r] [-t] [name…] -n # open new file (default name Untitled) -r # open file for read-only use -t # open file as the target window Status codes returned: 0 No errors. 1 Error in parameters. 2 Unable to complete operation; specified file not found. 3 System error. Description Opens a file as the active (frontmost) window. If name is not specifed, StdFile’s GetFile routine is called, allowing you to use a dialog box to choose a file. If name is already open as a window, that window becomes the active (frontmost) window. Examples Open Displays StdFile from which to choose a file to open. Open -r -t Test.a Opens the file Test.a as the target window, read-only. Open ≈.a Opens all the files that end with ".a". See also Target, New, and Close commands. æKY OrphanFiles æC OrphanFiles -- remove Projector information from a list of files OrphanFiles file… Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. Description Remove the 'CKID' resource from file(s). This removes the identification information from the file that Projector uses to uniquely identify it. • Warning Once the projector information is removed from a file, you cannot check the file back into the Project as a checked-out file. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples Suppose file.c and interactive.c belong to a project that has been deleted. We can remove the Projector information from them (so that they can be used for other purposes) with the command OrphanFiles file.c interactive.c See also TransferCkid. æKY Parameters æC Parameters -- write parameters Parameters [parameter…] > parameters Status codes returned: 0 no errors is always returned. Description The Parameters command writes its parameters, including its name, to standard output. The parameters are written one per line, and each is preceded by its parameter number (in braces) and a blank. This command is useful for checking the results of variable substitution, command substitution, quoting, blank interpretation, and filename generation. Examples Parameters One Two "and Three" Writes the following four lines to standard output: {0} Parameters {1} One {2} Two {3} and Three Recall that "…" and '…' quotation marks are removed before parameters are passed to commands. See also Echo and Quote commands. "Parameters to Scripts" in Chapter 5. æKY Pascal æC Pascal -- Pascal compiler Pascal [option…] [file…] < file ≥ progress -b # generate A5 references for procedure addresses -c # syntax check only, don't create object file -clean # erase all symbol table resources -d name=(TRUE|FALSE) # set compile time variable name -e file # write errors to file -forward # allow only explicit forward and external object declarations -h # suppress error messages regarding unsafe handles -i directory,… # search for includes in directory,… -k directory # create symbol table resource files in directory -m # allow greater than 32K globals by using 32 bit -mbg ch8 # include v2.0 compatible MacsBug symbols -mbg full # include full (untruncated) symbols for MacsBug -mbg off # don't include symbols for MacsBug -mbg number # include MacsBug symbols truncated to length # number -mc68020 # generate MC68020 code -mc68881 # generate MC68881 code for floating point operations -model farCode| # generate load-time relocatable 32-bit references for farData|far # code, data, or both -model nearCode| # generate 16-bit references for code, data, or both nearData|near # (the default) -n # generate separate global data modules for better allocation -noload # don't use or create any symbol table resources -o objname # generate code in file or directory objname -only name… # only generate code for named modules -ov # generate code to test for overflow -opt off # don't apply code optimizations -opt on | full # choose level of code optimization (full is default); # can modify with [,nopeep] [,nostatic] -p # write progress information to diagnostics -r # don't generate range checking code -rebuild # rebuild all symbol table resources -sym off # don't generate SADE records -sym on | full # generate SADE records; can modify with [,nolines] [,notypes] [,novars] -t # write compilation time to diagnostics -u # initialize all data to $7267 for debugging use -w # don't perform peephole optimization -y directory # create temporary files in directory Status codes returned: 0 Successful completion. 1 Error in parameters. 2 Compilation halted. Description Compiles the specified Pascal source files (programs or units). You can specify zero or more filenames. Each file is compiled separately—compiling file Name .p creates object file Name .p.o. By convention, Pascal source filenames end in a ".p" suffix. See the MPW 3.0 Pascal Reference for details of the language definition. Examples Pascal Sample.p Compiles the Sample program provided in the PExamples folder. Pascal File1.p File2.p -r Compiles File1.p and File2.p, producing object files File1.p.o and File2.p.o but performing no range checking. • Note: Listing files are not produced directly by the compiler. Refer to the PasMat and PasRef tools. Availability The MPW Pascal compiler is available as a separate Apple product. See also PasMat and PasRef commands. MPW 3.0 Pascal Reference. æKY PasMat æC PasMat -- Pasca programs formatter PasMat [option…] [input [output]] < input > output ≥ progress -a # set a- disable CASE label bunching -b # set b+ enable IF bunching -body # set body+ to disable indenting procedure bodies -c # set c+ suppress Return before BEGIN -d # set d+ use {…} comment delimiters -e # set e+ capitalize identifiers -entab # replace multiple blanks with tabs -f # set f- disable formatting -g # set g+ group assignment and call statements -h # set h- disable FOR, WHILE, WITH bunching -i directory,… # search for includes in directory,… -in # set in+ process includes -k # set k+ indent statements between BEGIN and END -l # set l+ literally copy reserved words, identifiers -list file # write listings to file -n # set n+ group formal parameters -o width # set output line width (default 80) -p # write progress information to diagnostics -pattern -old-new- # modify include names, changing old to new -q # set q+ no special ELSE IF formatting -r # set r+ upper case reserved words -rec # set rec+ to indent field lists under defined id -s file # substitute identifiers based on pairs in file -t tab # set output tab setting (default 2) -u # rename identifiers to match first occurence -v # set v+ put THEN on separate line -w # set w+ upper case identifiers -x # set x+ suppress space around operators -y # set y+ suppress space around := -z # set z+ suppress space after commas -: # set :+ align colons in VAR declarations -@ # set @+ multiple CASE tags on separate lines -∂# # set #+ smart grouping of assignments and calls -_ # set _+ delete _ from identifiers Status codes returned: 0 Normal termination. 1 Parameter or option error. Description Reformats Pascal source code into a standard format, suitable for printouts or compilation. PasMat accepts full programs, external procedures, blocks, and groups of statements. • Note: A syntactically incorrect program causes PasMat to abort. If this happens, the generated output will contain the formatted source up to the point of the error. PasMat options let you do the following: • Convert a program to uniform case conventions. • Indent a program to show its logical structure, and adjust lines to fit into a specified line length. • Change the comment delimiters ( * * ) to { } . • Remove the underscore character ( _ ) from identifiers, rename identifiers, or change their case. • Format include files named in MPW Pascal include directives. PasMat specifications can be made through PasMat options or through special formatter directives, which resemble Pascal compiler directives, and are inserted into the source file as Pascal comments. PasMat’s default formatting is straightforward and does not require you to use any options. The best way to find out how PasMat formats something is to try out a small example. See Appendix K of the MPW 3.0 Pascal Reference for details of PasMat directives and their functions. The first dialog box of the Pascal Commando dialog is reproduced here for your convenience. Examples Pasmat -n -u -r -d -pattern "==formatted/=" Sample.p ∂ "formatted/Sample.p" Formats the file Sample.p with the -n, -u, -r, and -d options and writes the output to the file "formatted/Sample.p". Include files are processed ( -pattern ), and each Pascal compiler $I include file causes additional output files to be generated. Each of these files is created with the name "formatted/ filename ", where filename is the filename specified in the corresponding include. (The -pattern parameter contains a null pattern (==) with "formatted/" as a replacement string—a null pattern always matches the start of a string.) Care must be taken when a command line contains quotes, slashes, or other special characters that are processed by the Shell itself. In this example, we used the slash character, so the strings containing it had to be quoted. Limitations PasMat has these limitations: • The maximum length of an input line is 255 characters. • The maximum output line length is 150 characters. • The input files and output files must be different. • Only syntactically correct programs, units, blocks, procedures, and statements are formatted. This limitation must be taken into consideration when separate MPW 3.0 include files and conditional compiler directives are to be formatted. • The Pascal include directive should be the last thing on the input line if include files are to be processed. Include files are processed to a maximum nesting depth of five. All include files not processed are summarized at the end of formatting. (This assumes, of course, that the in directive/option is in effect.) • The identifiers CYCLE and LEAVE are treated as reserved Pascal keywords by PasMat. They are treated as two loop control statements by Pascal unless explicitly declared. • While Pasmat supports Pascal’s $$Shell facility in include files, the processing of MPW’s {PInterfaces} files is not fully supported because these files conditionally include files (remember, conditionals are not processed). For this reason, do not use the -in or -e option to process files that include MPW {PInterfaces} files. Availability PasMat is available as part of a separate Apple product, MPW 3.0 Pascal . See also Pascal and PasRef commands. Appendix K of the MPW 3.0 Pascal Reference. æKY PasRef æC PasRef -- Pascal cross-referencer PasRef [option…] [file…] < file > crossReference ≥ progress -a # process includes and units each time encountered -c # process includes and units only once -cond # process $SETC and $IFC, $ELSEC, $ENDC conditionals -d # process each file separately -d name=TRUE|FALSE # set $SETC variable name to TRUE or FALSE -i directory,… # search for includes in directory,… -l # write identifiers in lower case -mc68020 # source contains {$IFC OPTION(MC68020)} directives -mc68881 # source contains {$IFC OPTION(MC68881)} directives -n # don't process USES or includes -ni | -noi[ncludes] # don't process include files -nl | -nol[istings] # don't list the input -nolex # don't write lexical information -nt | -not[otal] # don't write total line count -nu | -nou[ses] # don't process USES declarations -o # source written using Object Pascal -p # write progress information to diagnostics -s # don't write include and USES filenames -t # cross reference by total line number -u # write identifiers in upper case -w width # set output line width (default 110) -x width # set maximum identifier width Status codes returned: 0 Normal termination. 1 Parameter or option error. Description Reads Pascal source files and writes a listing of the source followed by a cross-reference listing of all identifiers. Each identifier is listed in alphabetical order, followed by the number of the line on which it appears. Line numbers can refer to the entire source file, or can be relative to individual include files and units. Each reference indicates whether the identifier is defined, assigned, or simply named (for example, used in an expression). See the MPW 3.0 Pascal Reference for more information about the Pascal language. The first dialog box of PasRef’s Commando dialog is reproduced here for your convenience. Identifiers may be up to 63 characters long and are displayed in their entirety unless overridden with the -x directive. Identifiers can remain as they appear in the input, or they can be converted to all lowercase (-l ) or all uppercase (-u). For include files, line numbers are relative to the start of the include file; an additional key number indicates which include file is referred to. A list of each include file processed and its associated key number is displayed prior to the cross-reference listing. USES declarations can also be processed by PasRef (their associated $U filename compiler directives are processed as in the Pascal compiler). These declarations are treated exactly like includes, and, as with the compiler, only the outermost USES declaration is processed (that is, a used unit’s USES declaration is not processed). As an alternative to processing USES declarations, PasRef accepts multiple source files. Thus you cross-reference a set of main programs together with the units they use. All the sources are treated like include files for display purposes. In addition, PasRef checks to see whether it has already processed a file (for example, if it appeared twice on the input list, or if one of the files already used or included it). The file is skipped it has already been processed. Examples PasRef -nu -w 80 Memory.p > Memory.p.Xref Cross-references the sample desk accessory Memory.p and writes the output to the file Memory.p.Xref. No USES declarations are processed (-nu). The following source and cross-reference listings are generated: 1 1 1 -- { 2 1 2 -- File Memory.p 3 1 3 -- 4 1 4 -- Copyright Apple Computer, Inc. 1985-1987 5 1 5 -- All rights reserved. 6 1 6 -- } 7 1 7 -- 8 1 8 -- {$D+} { MacsBug symbols on } 9 1 9 -- {$R-} { No range checking } 10 1 10 -- 11 1 11 -- UNIT Memory; 12 1 12 -- 13 1 13 -- INTERFACE 14 1 14 -- 15 1 15 -- USES 16 1 16 -- MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf; 17 1 17 -- 18 1 18 -- 19 1 19 -- FUNCTION DRVROpen (ctlPB: ParmBlkPtr; dCtl: DCtlPtr):OSErr; 20 1 20 -- FUNCTION DRVRControl (ctlPB: ParmBlkPtr; dCtl: DCtlPtr):OSErr; 21 1 21 -- FUNCTION DRVRStatus (ctlPB: ParmBlkPtr; dCtl:.DCtlPtr):OSErr; 22 1 22 -- FUNCTION DRVRPrime (ctlPB: ParmBlkPtr; dCtl: DCtlPtr):OSErr; 23 1 23 -- FUNCTION DRVRClose (ctlPB: ParmBlkPtr; dCtl: DCtlPtr):OSErr; 24 1 24 -- 25 1 25 -- 26 1 26 -- IMPLEMENTATION etc. 63 1 63 --A FUNCTION DRVRClose (ctlPB: ParmBlkPtr; dCtl: DCtlPtr):OSErr; 64 1 64 0-A BEGIN 65 1 65 -- IF dCtl^.dCtlwindow <> NIL THEN 66 1 66 1- BEGIN 67 1 67 -- DisposeWindow (WindowPtr(dCtl^.dCtlWindow)); 68 1 68 -- dCtl^.dCtlWindow := NIL; 69 1 69 -1 END; 70 1 70 -- DRVRClose := NOErr; 71 1 71 -0A END; etc. 178 1 178 -- 179 1 179 -- END. {of memory UNIT} 180 1 180 -- Each line of the source listing is preceded by five columns of information: 1. The total line count. 2. The include key assigned by PasRef for an include or USES file. (See below.) 3. The line number within the include or main file. 4. Two indicators (left and right) that reflect the static block nesting level. The left indicator is incremented (mod 10) and displayed whenever a BEGIN, REPEAT, or CASE is encountered. On termination of these structures with an END or UNTIL, the right indicator is displayed, then decremented. It is thus easy to match BEGIN, REPEAT, and CASE statements with their matching terminations. 5. A letter that reflects the static level of procedures. The character is updated for each procedure nest level ("A" for level 1, "B" for level 2, and so on), and displayed on the line containing the heading, and on the BEGIN and END associated with the procedure body. Using this column you can easily find the procedure body for a procedure heading when there are nested procedures declared between the heading and its body. The cross-reference listing follows: 1. Memory.p -A- accEvent 144 ( 1) accRun 158 ( 1) ApplicZone 121 ( 1) Away 33* ( 1) 146 ( 1) -B- BeginUpdate 151 ( 1) BNOT 39 ( 1) Bold ( 1) 117 ( 1) Boolean 31* ( 1) BOR 39 ( 1) BSL 39 ( 1) -C- csCode 143 ( 1) CSParam 146 ( 1) ctlPB 19* ( 1) 20*( 1) 21*( 1) 22*( 1)..23*( 1) 43*( 1) 63* ( 1) 74*( 1) 143 ( 1) 146 ( 1) 168*( 1) 173*( 1) -D- dCtl 19* ( 1) 20*( 1) 21*( 1) 22*( 1) 23*( 1) 37*( 1) 39 ( 1) 43*( 1) 50 ( 1) 53 ( 1) 54 ( 1) 55 ( 1) 63* ( 1) 65 ( 1) 67 ( 1) 68 ( 1) 74*( 1) 115 ( 1) 142 ( 1) 168*( 1) 173*( 1) DCtlPtr 19 ( 1) 20 ( 1) 21 ( 1) 22 ( 1) 23 ( 1) 37 ( 1) 43 ( 1) 63 ( 1) 74 ( 1) 168 ( 1) 173 ( 1) dCtlRefNum 39 ( 1) 54 ( 1) dCtlWindow 50 ( 1) 55=( 1) 67 ( 1) 68=( 1) 142 ( 1) etc. -V- VolName 79* ( 1) 100 ( 1) 135 ( 1) -W- what 149 ( 1) WindowKind 54= ( 1) windowpeek 54 ( 1) WindowPtr 48 ( 1) 67 ( 1) 151 ( 1) 153 ( 1) wRect 47* ( 1) *** End PasRef: 105 id's 249 references The numbers in parentheses following the line numbers are the include keys of the associated include files (shown in column 2 of the source listing). The include filenames are shown following the source listing. You can thus see what line number was in which include file. An asterisk (*) following a line number indicates a definition of the variable. An equal sign (=) indicates an assignment. A line number with nothing following it indicates a reference to the identifier. Limitations PasRef has these limitations: • PasRef does not process conditional compilation directives! Thus, given the "right" combination of $IFCs and $ELSECs, PasRef’s lexical (nesting) information can be thrown off. If this happens, or if you don’t want the lexical information, you can specify the -nolex option. • PasRef stores all its information on the Pascal heap. Up to 5000 identifiers can be handled, but more identifiers will mean less cross-reference space. A message appears if PasRef runs out of heap space. • Note: Although PasRef never misses a reference, it can infrequently be fooled into thinking that a variable is defined when it actually isn’t. One case where this happens is in record structure variants. The record variant’s case tag is always flagged as a definition (even when there is no tag type) and the variant’s case label constants (if they are identifiers) are also sometimes incorrectly flagged, depending on the context. (This occurs only in the declaration parts of the program.) • While PasRef supports Pascal’s $$Shell facility in include files and USES declarations, the processing of MPW’s {PInterfaces} files is not fully supported because these files conditionally include files (remember, conditionals are not processed). For this reason, always use the -nu option to suppress processing of USES declarations. • The identifiers CYCLE and LEAVE are treated as reserved Pascal keywords by PasRef. These are treated as two loop control statements by Pascal unless explicitly declared. Availability PasRef is available as part of a separate Apple product, MPW 3.0 Pascal. See also Pascal command. MPW 3.0 Pascal Reference. æKY Paste æC Paste -- replace selection with Clipboard contents Paste [-c count] selection [window] -c count # repeat the Paste count times Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Any other error. Description Finds selection in the specified window and replaces its contents with the contents of the Clipboard. If no window is specified, the command operates on the target window (the second window from the front). It’s an error to specify a window that doesn’t exist. For a definition of selection, see "Selections" in Chapter 6 of the MPW manual; a summary of the selection syntax is contained in Appendix B. Examples Paste § Replaces the current selection with the contents of the Clipboard. This command is like the Paste item in the Edit menu, except that the action occurs in the target window. Paste /BEGIN/:/END/ Selects everything from the next BEGIN to the following END and replaces the selection with the contents of the Clipboard. See also Copy, Cut, and Replace commands. "Edit Menu" in Chapter 3. "Selections" in Chapter 6. æKY PerformReport æC PerformReport -- generate a performance report PerformReport [option…] > reportFile ≥ progress -a # list all procedures, in segment order # (default: produce only partial list, sorted by %) -l linkDataFile # read link map file (concatenated with ROM.list) -m measurementsFile # read performance measurements file # (default: "Perform.Out") -n NN # show the top NN procedures (default: 50) -p # write progress information to diagnostics Status codes returned: 0 No errors. 1 Warning issued. 2 Error encountered. 3 Heap error;usually insufficient memory. Description PerformReport reads a link map file and a performance data file and produces a report that relates the performance data to procedure names. The input files are both text files and are distinguished as separate options. For a full discussion of MPW’s performance measurement tools, see Chapter 14 of the MPW manual. Examples Catenate "{MPW}"ROM.Maps:MacIIROM.map >> myMapFileName PerformReport -l myMapFileName > myReport Adds the ROM map file to the end of the link map file, myMapFileName. Reads the files myMapFileName and Perform.out and writes the output to myReport. See also Chapter 14, "Performance-Measurement Tools." MPW 3.0 Pascal Reference. MPW 3.0 C Reference . æKY Position æC Position -- display current line position Position [-l | -c] [window…] -l # only list the line number -c # only list the character offsets Status codes returned: 0 No errors. 1 Syntax error. 2 Any other error. Description Position displays the position of the selection in each of the windows specified. If no window is specified, the position of the selection in the Target window is given. By default, the position is displayed as both the line number of the start of the selection and the character positions of the start and end of the selection. The -c option can be used to display only the character positions of the selection. Similarly, the -l option can be used to display only the line number. Examples Position {Target} file2 Displays the position of the selection in both the Target and file2 in the following form: 578 23129,23140 211 8440,8440 See also Find command. æKY Print æC Print -- print text files Print [option…] file… < file ≥ progress -b # print a border around the text -b2 # alternate form of border -bm n[.n] # bottom margin in inches (default 0) -c[opies] n # print n copies -ff string # treat "string" at beginning of line as a formfeed -f[ont] name # print using specified font -from n # begin printing with page n -h # print headers (time, file, page) -hf[ont] name # print headers using specified font -hs[ize] n # print headers using specified font size -l[ines] n # print n lines per page -lm n[.n] # left margin in inches (default .2778) -ls n[.n] # line spacing (2 means double-space) -md # use modification date of file for time in header -n # print line numbers to left of text -nw [-]n # width of line numbers, - indicates zero padding -p # write progress information to diagnostics -page n # number pages beginning with n -ps filename # include PostScript file as background for each page -q quality # print quality (HIGH, STANDARD, DRAFT) -r # print pages in reverse order -rm n[.n] # right margin in inches (default 0) -s[ize] n # print using specified font size -t[abs] n # consider tabs to be n spaces -title title # include title in page headers -tm n[.n] # top margin in inches (default 0) -to n # stop printing after page n Status codes returned: 0 Successful completion. 1 Parameter or option error. 2 Execution error. Description Prints text files on the currently selected printer. (Printers are selected with the Chooser desk accessory.) One or more files may be printed. • Note: Print does not substitute fonts unless the "Font Substitution" box is checked in the "LaserWriter Page Setup" dialog. To print in a font other than that indicated in the resource fork of the file where the MPW editor stores font information, use the -font option. • Important Print requires the printer drivers available on version 1.0 (or later) of the Printer Installation disk. Examples Print -h -size 8 -ls 0.85 Startup UserStartup Prints the files Startup and UserStartup with page headers, using Monaco 8 and compressing the line spacing. Print -b -hf helvetica -hs 12 -r print.p Prints the "print.p" source file with borders, with headers in Helvetica 12, and with pages in reverse order. See also Print menu item in "File Menu," Chapter 3. æKY ProcNames æC ProcNames -- display Pascal procedure and function names ProcNames [option…] [file…] < file ≥ progress -b # display line info for procedure body -c # process includes and units only once -cond # process $SETC and $IFC, $ELSEC, $ENDC conditionals -d # reset total line count to 1 on each new file -d name=TRUE|FALSE # set $SETC variable name to TRUE or FALSE -e # suppress page eject between each procedure listing -f # PasMat format compatibility mode -i pathname,… # search for includes or USES in directory,… -l n # process only to max nesting level n -m # generate MPW Mark commands for procedure and function declarations -mc68020 # source contains {$IFC OPTION(MC68020)} directives -mc68881 # source contains {$IFC OPTION(MC68881)} directives -n # suppress line number and level information -o # source file is an Object Pascal program -p # write progress information to diagnostics -u # process USES declarations Status codes returned: 0 Normal termination. 1 Parameter or option error. Description ProcNames is a Pascal utility that accepts a Pascal program or unit as input and produces a listing of all its procedure and function names. The names are shown indented as a function of their nesting level. The nesting level and line-number information is also displayed. ProcNames can be used in conjunction with the Pascal "pretty-printer" PasMat when that utility is used to format separate include files. For that case, PasMat requires that the initial indenting level be specified. This level is exactly the information provided by ProcNames. The line-number information displayed by ProcNames exactly matches that produced by the Pascal cross-reference utility PasRef (with or without USES declarations being processed), so ProcNames can be used in conjunction with the listing produced by PasRef to show just the line numbers of every procedure or function header. Another possible use for the ProcNames output is to use the line-number and file information to find procedures and functions quickly with Shell editing commands. Examples procnames Memory.p >names Lists all the procedures and functions for the Pascal program Memory.p and writes the output to the file "names". The listing below is the output generated in the "names" file. Procedure/Function names for Memory.p 11 11 0 Memory[Main] Memory.p 37 37 1 RsrcID 43 43 1 DRVROpen 63 63 1 DRVRCloseaa 74 74 1 DRVRControla 76 76 2 DrawWindow 83 83 3 PrintNum 93 93 3 GetVolStuff 108 108 3 PrtRsrcStr 168 168 1 DRVRPrime 173 173 1 DRVRStatus *** End ProcNames: 11 Procedures and Functions The first two columns on each line are line-number information. The third column is the level number. The first column shows the line number of a routine within the total source. The second column shows the line number within an include file (include files are always processed). As each include file changes, the name of the file from which input is being processed is shown along with the routine name on the first line after the change in source. Segment names (from Pascal compiler $S directives) are similarly processed. These are shown enclosed in square brackets (the blank segment name is shown as "[Main]"). Limitations Only syntactically correct programs are accepted by ProcNames. Conditional compilation compiler directives are not processed. Although ProcNames supports $$Shell facility in includes and USES, the processing of MPW’s {PInterfaces} files is not fully supported because these files conditionally include files. Therefore, do not use the -u option. æKY Project æC Project -- set or write the current project Project [-q | projectName] > project -q # don't quote projects with special characters Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. Description Set the current project to projectname or list the current project if projectname is omitted. Projectname must be a mounted project. Refer to the MountProject command for information on how to mount projects. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. æKY ProjectInfo æC ProjectInfo -- display information about a Project ProjectInfo [-project project] [-comments] [-latest] [-f] [-r] [-s] [-only | -m] [-af author | -a author] [-df dates | -d dates] [-cf pattern | -c pattern] [-t pattern] [-n name] [-newer | -update] [file…] -a author # only list revisions created by author -af author # only list files created by author -c pattern # only list revisions whose comment contains pattern -cf pattern # only list files whose comment contains pattern -comments # list comments along with the rest of the information -d dates # only list revisions whose create date is within dates -df dates # only list files whose mod date is within dates -f # list file information -log # print project log -m # only list files/revisions that are checked out -newer # info on files that would be checked out using this option -only # only list project information -project project # name of project to get information on -r # recursively list subprojects -latest # only list info on the latest revision on the main trunk -s # short listing, names and revision names only -t pattern # only list revisions whose task contains pattern -n name # only list revisions that have name -update # info on files that would be checked out using this option Note: pattern is either a literal string or /regular expression/. Note: "dates" may take the following forms: date # on date <date # before but not including date ≤date # before and including date >date # after and not including date ≥date # after and including date date-date # between and including dates Note: A date is mm/dd/yy [[hh:mm[:ss]] [AM|PM]] Note: "name" may take the following forms: name # in name <name # before name ≤name # before and including name >name # after name ≥name # after and including name Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description By default (with no options specified), ProjectInfo lists information about each revision in every revision tree (file) in the current project. This behavior can be changed using the various options. For example, using the -latest option will display only information about the latest revision on the main trunk of each revision tree. Using the -f option will display information about the revision tree, rather than the particular revisions within that tree. Various other options exist that filter the output such that only the information (typically revisions) that passes through the filter is listed. If object is a project pathname such as Enterprise∫Phaser∫file.c or Enterprise∫Phaser, Projector lists information about every revision of file.c in the Phaser project, or information about every revision tree in the project Enterprise∫Phaser, respectively. If object is a leafname such as file.c, Projector looks in the current project for a revision tree with that name. If found, information about every revision in that revision tree (file.c) is listed. If the file is not a member of the current project, Projector looks for the file in the current directory. If the file exists and is part of a project, then the current state of that file is listed. Projector can determine whether a file belongs to a project because that information is maintained in the resource fork of all checked-out files. Finally, if object is a valid partial or full HFS pathname of a file, and the file is part of a project, then the current state of that file is listed. To list the contents of a specific revision of a file, append a comma followed by the revision number to the filename specified. For example, revision 22 of file.c is specified as file.c,22. You can use the -af, -a, -df, -d, -n, -cf, -c, and -t options to filter (constrain) the information listed to specific authors, dates, names, specific comments, or tasks. Use the -log option to display a log of all changes to the project. These commands are logged: NameRevisions, DeleteRevisions, and DeleteNames. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples In the example below, the current project has three files. The -latest option is used so that only information about the latest revision on the main trunk is listed. The presence of the plus sign (+) indicates that Bob currently has revision 22 of file.c checked out for modification, and that Peter has revision 33 of hdr.c checked out for modification. The date field of these two files reflects the date and time they were checked out. Because no plus sign appears on the line for file.h, it can be checked out for modification. The latest revision of file.h is 17, and the author of the revision is Bob. ProjectInfo -latest Sample∫ file.c,22+ Owner: Bob Checked out: Fri, Apr 8, 1988, 3:45 PM Task: Fixing bug #223 file.h,17 Author: Bob Checked in: Mon, Apr 4, 1988, 10:10 AM Task: hdr.c,33+ Owner: Peter Checked out: Tue, Apr 12, 1988, 5:58 PM Task: Fixing bug #333 Using the -only option causes ProjectInfo to list only information about the project itself. ProjectInfo -only Sample∫ Author: Bob Create date: Mon, Apr 4, 1988 8:20 AM Mod date: Thu, Apr 14, 1988, 6:00 PM Use the -f option to list filenames. Note that revision numbers are absent and that the file’s author and last-mod-date are listed. In the example below, file.c and hdr.c are currently checked out. ProjectInfo -f Sample∫ file.c Author: Bob Create date: Mon, Apr 4, 1988, 10:00 AM Mod date: Tue, Apr 5, 1988, 2:15 PM Free: No file.h Author: Bob Create date: Mon, Apr 4, 1988, 10:00 AM Mod date: Mon, Apr 4, 1988, 10:00 AM Free: Yes hdr.c Author: Peter Create date: Mon, Apr 4, 1988, 3:30 PM Mod date: Mon, Apr 4, 1988, 6:00 PM Free: No Use the -f and -s options together to output the list of files in the project: ProjectInfo -f -s Sample∫ file.c file.h hdr.c The following command will display the entire revision history of file.c. Note that the comment option has been included here as well. ProjectInfo -comments file.c file.c,2+ Owner: Bob Checked out: Fri, Apr 8, 1988, 3:45 PM Task: Fixing bug #223 Comment: COMMENT… file.c,2 Author: Bob Checked in: Thu, Apr 7, 1988, 1:10 PM Task: Fixing bug #222 Comment: COMMENT… file.c,1 Author: Bob Checked in: Mon, Apr 4, 1988, 9:25 PM Task: Updating procedure comments Comment: COMMENT… Information about HFS files may be displayed by specifying a partial or full HFS pathname. This displays the information in the 'ckid' resource of the file. ProjectInfo :file.c :file.c,22* Owner: Bob Project: Sample∫ Checked out: Fri, Apr 8, 1988, 3:45 PM Task: Fixing bug #223 The asterisk (*) following the name indicates that the file is a modified read-only file. In the example below, only revisions created by Bob and created on or after April 4, 1988, are displayed. ProjectInfo -a Bob -d Sample∫ file.c,22+ Owner: Bob Checked out: Fri, Apr 8, 1988, 3:45 PM Task: Fixing bug #223 file.c,22 Author: Bob Checked in: Thu, Apr 7, 1988, 1:10 PM Task: Fixing bug #222 file.c,21 Author: Bob Checked in: Mon, Apr 4, 1988, 9:25 PM Task: Updating procedure comments file.h,17 Author: Bob Checked in: Mon, Apr 4, 1988, 10:10 AM Task: In the example below, only revisions that have a task dealing with Bug #222 are listed. ProjectInfo -t /bug≈222/ Sample∫ file.c,22 Author: Bob Checked in: Thu, Apr 7, 1988, 1:10 PM Task: Fixing bug #222 hdr.c,31 Author: Peter Checked in: Fri, Apr 1, 1988, 3:50 PM Task: Bug222 - Adding check procedure The final example demonstrates the -log option. ProjectInfo -log TheShell∫Projector 7/5/88 4:07 PM Peter J. Potrebic DeleteNames Work 7/2/88 1:37 PM Peter J. Potrebic NameRevisions Work bitmaps.a,2 ckid.c,3a2 The log shows that Peter created a public name on July 2 and then deleted it on July 5. See also MountProject and UnmountProject. æKY Quit æC Quit -- quit MPW Quit [-y | -n | -c] -y # save all modified windows (avoids dialog) -n # do not save any modified windows (avoids dialog) -c # cancel if a window needs to be saved (avoids dialog) Status codes returned: 1 Syntax error. 2 Command aborted. Note: Quit cannot return a status of 0, because if there are no errors the command never returns. Description This command is equivalent to the menu command Quit. Quit executes the standard quit procedures, asking confirmation to save modified files, close all windows, and so on. Examples Quit -y Quits MPW answering "Yes" to any dialogs such as those prompting to save files. Quit -c Quits MPW, unless any confirmation dialogs occur and dialog boxes are displayed. See also Shutdown command. æKY Quote æC Quote -- echo parameters, quoting if needed Quote [-n] [parameter…] > parameters -n # don't write return following the parameters Status codes returned: 0 no errors always returned. Description Quote writes its parameters, separated by spaces and terminated by a return, to standard output. Parameters containing characters that have special meaning to the Shell’s command interpreter are quoted with single quotation marks. If no parameters are specified, only a return is written. Quote is identical to Echo except that Quote quotes parameters that contain special characters. Quote is especially useful when using Shell commands to write a script. The following special characters are quoted: Space Tab Return Null # ; & | ( ) ∂ ' " / \ { } ` ? ≈ [ ] + * « » ® < > ≥ … Examples Echo ≈.a Quote ≈.a Sample.a Count.a My Program.a Sample.a Count.a 'My Program.a' Echo and Quote behave slightly differently for parameters that contain special characters. The first line above was produced by Echo; the second by Quote. Quote Notice what happens to single quotes: "--'--" Notice what happens to single quotes: '--'''--' Because single quotes can’t appear within single quotes, they are replaced with '' ' which closes the original single quote, adds a literal quote, and reopens the single quotes. For file In ≈.a Quote Print "{file}" End Print Sample.a Print Count.a Print 'My Program.a' The For loop shown above writes a Print command for each file that matches the pattern ≈.a. These commands can then be selected and executed. Notice the quotation marks in the last Print command. See also Echo and Parameters commands. æKY Rename æC Rename -- rename files and directories Rename [-y | -n | -c] oldName newName -y # overwrite existing file (avoids dialog) -n # don't overwrite existing file (avoids dialog) -c # cancel if conflict occurs (avoids dialog) Status codes returned: 0 Successful rename. 1 Syntax error. 2 Name does not exist. 3 An error occurred. 4 Cancel was selected or implied by the -c option. Description The file, folder or disk specified by name is renamed newName. A dialog box requests a confirmation if the rename would overwrite an existing file or folder. The -y, -n, or -c options can be used to avoid this interaction. • Note: You can’t use the Rename command to change the directory a file is in. To do this, use the Move command. • Note also: Wildcard renames in the following form will not work: Rename ≈.text ≈.p This is because the Shell expands the filename patterns "≈.text" and "≈.p" before invoking the Rename command. In order to gain the desired effect, you would need to execute a command such as the one shown in the fifth example below. Examples Rename File1 File2 Changes the name of File1 to File2. Rename HD:Programs:Prog.c Prog.Backup.c Changes the name of Prog.c in the directory HD:Programs to Prog.Backup.c in the same directory. Rename Untitled: Backup: Changes the name of the disk Untitled to Backup. Rename -c File1 File2 Changes the name of File1 to that of File2; if a conflict occurs, it cancels the operation and returns a status of 4. To perform a wildcard rename, you could execute the following set of commands: For Name In ≈.text ( Evaluate {Name} =~ /(≈)®1.text/ ) > Dev:Null Rename {Name} {®1}.p End The Evaluate command is executed only for its side effect of permitting regular expression processing. (The expression operator =~ indicates that the right side of the expression is a regular expression.) Thus, you can use the regular expression capture mechanism, (regularExpr)®n. Evaluate’s output is tossed in the bit bucket (Dev:Null). See also Move command. æKY Replace æC Replace -- replace the selection Replace [-c count] selection replacement [window] -c count # repeat the replace count times Status codes returned: 0 At least one instance of the selection was found. 1 Syntax error. 2 Any other error. Description Replace finds selection in the specified window and replaces it with replacement. If no window is specified, the command operates on the target window (the second window from the front). It’s an error to specify a window that doesn’t exist. If a count is specified, the Replace command is repeated count times. For a definition of selection, see "Selections" in Chapter 6 of the MPW manual. A summary of the selection syntax is contained in Appendix B. You can include references to parts of the selection in the replacement by using the ® operator. The expression ®n, where n is a digit, is replaced with the string of characters that matches the regular expression tagged by ®n in the selection. (See "Tagging Regular Expressions With the ® Operator" in Chapter 6.) The selection is a selection expression while replacement is a string (that could contain the ® operator). If replacement contains spaces or special characters, enclose it in quotation marks. All searches are by default not case sensitive. To specify case-sensitive matching, set the {CaseSensitive} variable before executing the command. Examples Replace -c ∞ /myVar/ 'myVariable' Prog.p Replaces every subsequent instance of the selection with the string in single quotation marks. Replace -c 5 /•[ ]+/ '' Strips off all the spaces and tabs at the front of the next five lines in the file (and replaces them with the null string). This action takes place in the target window. Set HexNum "[0-9A-F]+" Set Spaces "[ ]+" Replace -c ∞ /({HexNum})®1{Spaces}({HexNum})®2/ ®1 ®2 Defines two variables for use in the subsequent Replace command, and converts a file that contains two columns of hex digits (such as the icon list from ResEdit) into a single column of hex digits. See also Find and Clear commands. Chapter 6. Appendix B. æKY Request æC Request -- request text from a dialog box Request [-q] [-d default] [message…] < file -q # don't set status if user selects cancel -d default # set default response Status codes returned: 0 The OK button was selected. 1 Syntax errors. 4 The Cancel button was selected. Description Request displays an editable text dialog box with OK and Cancel buttons and the prompt message. If you select the OK button, any text you type into the dialog box is written to standard output. The -d option lets you set a default response to the request. Examples Set Exit 0 Set FileName "`Request 'File to compile' -d "{Active}"`" If {FileName} ≠ "" Pascal "{FileName}" ≥≥ "{WorkSheet}" End Set Exit 1 Displays a dialog box that lets the user enter the name of a file to be compiled. Sets the default to be the name of the active window, as follows: æKY ResEqual æC ResEqual -- compares the resources in two files ResEqual [-p] File1 File2 -p # write progress information to diagnostics Status codes returned: 0 Resources match. 1 Parameter or option error. 2 Files don’t match. Description ResEqual compares the resources in two files and writes their differences to standard output. ResEqual checks that each file contains resources of the same type and identifier as the other file; that the size of the resources with the same type and identifier are the same; and that their contents are the same. Examples Resequal Sample Sample.rsrc Compares the resources in Sample and Sample.rsrc, writing the results to standard output. Limitations When the contents of resources are compared and a mismatch is found, the mismatch and the subsequent 15 bytes are written. ResEqual then continues the comparison, starting with the byte following the last displayed. If more than ten differences are detected in the same resource, the rest of the resource is skipped and processing continues with the next resource. See also Equal command. (The -r option of Equal compares the resource forks of files on a byte-by-byte basis, including the resource map.) æKY Revert æC Revert -- revert window to previous saved state Revert [-y] [window…] -y # revert to old version (without dialog) Status codes returned: 0 No errors. 1 Parameter or option error. 2 The specified window does not exist. 3 A system error occurred. 4 The Cancel button was selected. Description Reverts the specified windows to their previously saved states. If no window is specified, Revert works on the target window. Revert displays a confirmation dialog box, but you can avoid this dialog box by using the -y option to revert unconditionally to the last saved version of the document. Examples Revert Displays a confirmation dialog box for reverting the target window to its last saved state. Revert -y {Worksheet} Reverts unconditionally to last saved worksheet. See also Close and Save commands. æKY Rez æC Rez -- resource compiler Rez [option…] [file…] < file ≥ progress -a[ppend] # merge resource into output resource file -align word | longword # align resource to word or longword boundries -c[reator] creator # set output file creator -d[efine] name[=value] # equivalent to: #define macro [value] -i[nclude] pathname # path to search when looking for #include files -m[odification] # don't change the output file's modification date -o file # write output to file (default Rez.Out) -ov # ok to overwrite protected resources when appending -p # write progress information to diagnostics -rd # suppress warnings for redeclared types -ro # set the mapReadOnly flag in output -s[earch] pathname # path to search when looking for INCLUDE resources -t[ype] type # set output file type -u[ndef] name # equivalent to: #undef name Status codes returned: 0 No errors. 1 Error in parameters. 2 Syntax error in file. 3 I/O or program error. Description Rez compiles the resource fork of a file according to a textual description. The resource description file is a text file that has the same format as the output produced by DeRez, the resource decompiler. The data used to build the resource file can come directly from the resource description file(s) as well as from other text files (via #include and read directives in the resource description file) and from other resource files (via the include directive). Rez includes macro processing, full expression evaluation, and built-in functions and system variables. For information about Rez and the format of a resource description file, see Chapter 11 of the MPW manual. For a summary of the format of a resource description file, see Appendix D. Examples Rez Types.r Sample.r -o Sample Generates a resource fork for the file Sample, based on the descriptions in Types.r and Sample.r. See also DeRez and RezDet commands. Chapter 11 and Appendix D. Standard resource type declarations in the directory {RIncludes}: • Types.r • SysTypes.r • MPWTypes.r • Pict.r æKY RezDet æC RezDet -- detect inconsistencies in resources RezDet [option…] file… > dump -b[ig] # read resources one at a time, not all at once -d[ump] # write -show information, plus headers, lists, etc. -l[ist] # write list of resources with minimum information -q[uiet] # don't write any output, just set {Status} -r[awdump] # write -dump information plus contents -s[how] # write information about each resource Note: Use at most one of -quiet, -list, -show, -dump, and -rawdump. Status codes returned: 0 No errors detected. 1 Invalid options or no files specified. 2 Resource format error detected. 3 Fatal error—an I/O or program error was detected. Description If no options are specified, RezDet investigates the resource fork of each file for damage or inconsistencies. The specified files are read and checked one by one. Output is generated according to the options specified. RezDet checks for the following conditions: • The resource fork is at least the minimum size. (There must be enough bytes to read a resource header.) • There is no overlap or space between the header, the resource data list, and the resource map. There should be no bytes between the EOF and the end of the resource map. • Each record in the resource data list is used once and only once. The last data item ends exactly where the data list ends. • Each item in the resource type list contains at least one reference; each sequence of referenced items starts where the previous resource type item’s reference list ended; and each item in the reference list is pointed to by one and only one resource type list item. • There are no duplicates in the resource type list. • Each name in the name list has one and only one reference, and the last name doesn’t point outside the name list. • There are no duplicate names in the name list. Duplicate names cause an advisory warning rather than a true error. This warning is given only if the -s, -d, or -r option is selected. • Each reference list item points to a valid data item and either has a name list offset of –1 or points to a valid name list offset. • Bits 7 (Unused), 1 (Changed), or 0 (Unused) should not be set in the resource attributes. • All names have a nonzero length. Fields are displayed as hexadecimal or decimal for numeric values, or as a hex dump with associated printable Macintosh characters. The characters newline ($0D), tab ($09) and null ($00) are displayed as "¬", "Δ", and ".", respectively. • Note: RezDet does not use the Resource Manager and should not crash, no matter how corrupt the resource fork of the file. Examples RezDet {SystemFolder}System Checks the System file for damage. RezDet -q Foo || Delete Foo Removes the file Foo if the resource fork is damaged. Limitations Duplicate resource name warnings are generated even if the names belong to resources of different types. The file attributes field in the resource map header is not validated. The Finder-specific fields in the header and resource map header are ignored. æKY RotateWindows æC RotateWindows -- send active (frontmost) window to back RotateWindows [-r] -r # reverse rotation; bring bottom window to front Status codes returned: 0 No errors. 1 Syntax error (error in parameters). Description RotateWindows places the front MPW window in the back and brings the second window to the front. Multiple calls to RotateWindows rotate through all open MPW windows. RotateWindows brings only MPW windows to the front (desk accessory windows are not rotated). You might want to add this command to a menu, along with a command key equivalent. For example: AddMenu 'Extras' 'RotateWindows/®' 'RotateWindows' Examples RotateWindows Puts the front MPW window in back, and brings the target MPW window to the front. See also StackWindows, SizeWindow, MoveWindow, and ZoomWindow commands. æKY Save æC Save -- save specified windows Save [-a | window…] -a # save the contents of all windows Status codes returned: 0 No errors. 1 Syntax error. 2 Specified window does not exist. Description Saves the contents of window or a list of windows to disk without closing them. The -a option saves all open windows. Save without any parameters saves the target window (the second window from the front). Examples Save -a Saves all open windows. Save {Active} {Worksheet} Saves the Worksheet window and the contents of the active window. See also Close and Revert commands. æKY SaveOnClose æC SaveOnClose -- set save behavior when closing windows SaveOnClose [-a | -d | -n] [window…] -a # always save upon close ("Close -y") -d # default behavior for Close -n # never save upon close ("Close -n") Description This command selects an automatic behavior: save, do not save, or ask whether to save when closing a window. The -n option does not turn off the Save menu item, allowing the user to request saving explicitly. æKY Search æC Search -- search files for pattern Search [-b] [-s | -i] [-nf] [-r] [-q] [-f file] pattern [file…] < file > found -b # break "File/Line" from matched pattern -i # case insensitive search (overriding {CaseSensitive}) -s # case sensitive search (overriding {CaseSensitive}) -nf # write "pattern not found" to standard error and set status = 2 -ns # return 0 when pattern not found -q # suppress file name and line number in output -r # write non-matching line to standard output -sf # stop at first match -f file # lines not written to output are put in this file Status codes returned: 0 No error. 1 Syntax error. 2 Pattern not found. Description Searches the input files for lines that contain a pattern and writes those lines to standard output. If no file is given, standard input is searched. When reading from files, the filenames and line numbers of matching lines are prepended to each line of output. Pattern (defined in "Pattern Matching" in Chapter 6 of the MPW manual and in Appendix B) is a regular expression, optionally enclosed in forward slashes ( / ). Examples Search /procedure/ Sample.p Searches the file Sample.p for the pattern "procedure". All lines containing this pattern are written to standard output. Search /Export/ {MPW}StartUp {MPW}UserStartUp Lists the Export commands in the StartUp and UserStartup files. Search /PROCEDURE [a-zA-Z0-9_]*;/ {PInterfaces}≈ Searches for the procedures with no parameters in the Pascal interface files supplied with MPW Pascal. Because more than one input file is specified, a filename will precede each line in the output. Search -f file.nonmatch /pattern/ file All lines of "file" that contain "pattern" are written to standard output. All other lines will be placed in file.nonmatch. This, in effect, splits the file in two pieces, using "pattern" as the key. Search -r -f file.nonmatch /pattern/ file This does the opposite of the preceding example. All lines that do not contain "pattern" are echoed to standard output, and all other lines (that is, those containing "pattern") are written to file.nonmatch. See also Find command. "Pattern Matching (Using Regular Expressions)" in Chapter 6. æKY Set æC Set -- define or write Shell variables Set [name [value]] > variableList Status codes returned: 0 No error. 1 Syntax error. 2 Variable "name" does not exist. Description Set assigns the string value to the variable name. If value is omitted, Set writes the name and its current value to standard output. If both name and value are omitted, Set writes a list of all variables and their values to standard output. (This output is in the form of Set commands.) • Note: To make variable definitions available to enclosed scripts and programs, you must use the Export command. Examples Set CIncludes "{MPW}CFiles:CIncludes:" Redefines the variable CIncludes. Set CIncludes Displays the new definition of CIncludes. Set Commands ∂ ":,{MPW}Tools:,{MPW}Applications:,{MPW}ShellScripts:" Redefines the variable {Commands} to include the directory "{MPW}ShellScripts:". (See Chapter 5 for a complete list of predefined variables.) Set > SavedVariables # ... other commands Execute SavedVariables Writes the values of all variables to file SavedVariables. Because the output of Set is actually Set commands, the file can be executed later to restore the saved variable definitions. This technique is used in the Suspend and Resume scripts to save and restore variable definitions, as well as exports, aliases, and menus. See also Export, Unexport, and Unset commands. "Defining and Redefining Variables" in Chapter 5. "The Startup and UserStartup Files" in Chapter 5. æKY SetDirectory æC SetDirectory -- set the default directory SetDirectory directory Status codes returned: 0 Successful completion. 1 Parameter error or unable to set directory. Description SetDirectory sets the default directory and adds the new default directory to the Directory menu if it is not already present. The directory parameter must be specified. • Note: Directory names should not contain any of the special characters shown below. These characters all have special meaning when they appear in menu items: - ; ^ ! < / ( The SetDirectory script is used to implement the Set Directory menu item in the Directory menu. Examples SetDirectory {MPW}Scripts: Sets the default directory to the Scripts folder in the {MPW} directory and adds {MPW}Scripts: to the Directory menu if it’s not already there. SetDirectory… Uses the Commando dialog box to select the default directory interactively. See also Directory, DirectoryMenu, and Files commands. æKY SetFile æC SetFile -- set file/folder attributes SetFile [option…] file/folder… -a attributes # attributes (lowercase = 0, uppercase = 1) -c creator # file creator -d date # creation date (mm/dd/yy [hh:mm[:ss] [AM | PM]])* -l h,v # ICON location (horizontal,vertical)* -m date # modification date (mm/dd/yy [hh:mm[:ss] [AM | PM]])* -t type # file type Note: Period (.) represents the current date and time. Note: The following attributes may be used with the -a option: L Locked V Invisible* B Bundle S System I Inited* D Desktop* M Shared (can run multiple times) A Always switch launch (if possible) *Note: Options/attributes marked with an asterisk (*) are allowed with folders Status codes returned: 0 The attributes for all files were set. 1 Syntax error. 2 An error occurred. Description Sets attributes for one or more files. The options apply to all files listed. Examples SetFile -c "MPS " -t MPST ResEqual Sets the creator and type for the MPW Pascal tool ResEqual. SetFile Foo -m "2/15/86 2:25" Sets the modification date of file Foo. SetFile Foo Bar -m . Sets the modification date to the current date and time (the period is a parameter to -m, indicating current date and time). Setting the date is useful, for instance, before running Make. See also Files command. (The -l and -x options display file information.) æKY SetPrivilege æC SetPrivilege -- set access privileges for directories on file servers SetPrivilege [option…] directory… > information -d privileges # set privileges for seeing directories -f privileges # set privileges for seeing files -g group # make the directories belong to group -i # return information on directories -m privileges # set privileges for making changes -o owner # make owner the owner of directories -r # operate (set or list) recursively Note: The following privilege characters may be used with the -d, -f, or -m options (Upper case enables the privilege, lower case disables it): O Owner G Group E Everyone Status codes returned: 0 No error. 1 Syntax error. 2 Folder not found, or folder not an AppleShare folder. 3 User is not owner; could not modify privileges. Description Using SetPrivilege is equivalent to using the access privileges desk accessory. Priv is a character string (one, two or three characters long) that specifies privileges for the owner, the group, and everyone (o, g, and e, respectively). An uppercase letter enables the privilege; a lowercase letter disables the privilege. If a specific character is not in the string, the respective privilege is not changed. Examples SetPrivilege -r -f OGe -d OGe -m Oge ∂ "Server:personal:peter" This gives everyone in your group the ability to see files within Server:personal:peter without being able to change them. Anyone outside the group cannot see the files or folders or make changes. The owner can do everything. Here is the easiest way to use the SetPrivilege command: Use the -i option to get information on folders and edit the privileges as desired. Then execute the resulting command. For example, to change the privileges for Server:Private, follow these steps: 1. Execute this command to obtain the current privileges: SetPrivilege -i Server:Private SetPrivilege Server:Private -o Joe -g Team -d OGE -f OGE -m OGE • Note: These privileges show that Joe, the group Team, and everyone else has all privileges to the folder Private. 2. Now edit the output, adjusting the privileges as desired. For example, SetPrivilege Server:Private -o Joe -g Team -d Oge -f Oge -m Oge • Note: Now only Joe, the owner, can see directories and files. Only Joe can make changes; all other users have no privileges. 3. Execute the resulting command. æKY SetVersion æC SetVersion -- maintain version and revision number SetVersion [option…] file > output ≥ progress -b # increment the bug fix component by 1 -country name # country code name -csource file # update the #define Version string in C source -d # display (updated) version numbers to standard output -fmt nƒ.mƒ # format version numbers according to specification -i resid # use specified resource id instead of 0 -p # write SetVersion's version info to diagnostic file -prefix prefix # prefix version with specified prefix -[p]source file # update the Version string constant in Pascal source -r # increment the revision component by 1 -rezsource file # update the resource definition in Rez source -sb bugfix # set the bug fix component to the specified value -sr revision # set the revision component to the specified value -stage stage # set release stage for a 'vers' resource -suffix suffix # suffix the version with specified suffix -sv version # set the version component to the specified value -sx nonrel # set the non-release component to the specified value -sync 1 | 2 # synchronize 'vers',1 with 'vers',2 or vice versa -t type # use specified resource type -v # increment the version component by 1 -verid identifier # use C/Pascal source version id instead of "Version" -version fmtstring # alternate way of specifying version component actions -verstring longstring # set the long version string of a Finder 'vers' resource -x # increment the non-release component by 1 Status codes returned: 0 Normal termination. 1 Parameter or option error. Description SetVersion generates and maintains (sets or increments) the individual components making up a version number for a file. There are two forms of version numbering supported by SetVersion: ver.rev The first version numbering form is "ver.rev", where ver is a version number and rev a revision number. The component values are kept in a private resource generated and maintained by SetVersion itself. The resource is generally used only by applications (for example, in their About box) and MPW tools (for example, when an MPW tool’s -p option is used) that contain code to read the resource. It is also recognized by Commando to be displayed just below the Do It button of a Commando dialog box1. In this form of version numbering, the resource is maintained as a Pascal string with the resource type 'MPST' and a resource ID of 0 (you can use the -t and -i options to specify another resource type and ID number if desired). The resource has the following layout (described as Rez input): Examples setversion -d -sv 1 -r Example -psource Globals -rezsource Example.r The MPW tool Example contains a SetVersion 'MPST' string resource. The above command line increments the revision for the tool (-r) in the resource fork of the file Example. The version is fixed at 1 (-sv), so that Example displays the version and revision as "1.rev". The Pascal include file, Globals, contains the tool’s global declarations, including the Version string. This include file is updated to match the 'MPST' resource (-psource). The resource definitions for the tools, in Example.r, will be similarly updated (-rezsource). Finally, this command displays the new version of the standard output file (-d). setversion -d -version 1.Δ Example -psource Globals -rezsource Example.r Same as previous example, but here we illustrate how the -version option serves the same purpose as the -sv and -r options. Here the "Δ" indicates that the revision is to be incremented. setversion -d -version 1.2.%bΔ Example -psource Globals ∂ -rezsource Example.r Again an 'MPST' SetVersion string resource is to be generated. But here we use a more complex version number. The version is set to 1, the revision to 2, the bug fix level is left alone ("%"), this is a beta (b) release, and finally the nonrelease level is to be incremented. SetVersion SetVersion -psource SetVersion.p -version 3.Δ -t vers -i 1 ∂ -d -verstring "^, ©Apple Computer, Inc. 1984-1988, by Ira L. Ruben" SetVersion SetVersion -version 3.0b1 -t vers -i 2 -verstring "MPW 3.0b1" This pair of SetVersion commands generates both Finder 'vers',1 and 'vers',2 resources. The Finder Get Info display shown earlier illustrates the result of using these commands. The MPW tool, SetVersion, has its own version number, 3.Δ (the revision is incremented for version 3) set as a 'vers',1 resource (-t 'vers', -i 1). A long version message is specified by the -verstring option. The version number from the short message string is inserted into the long string at the position indicated by the "^" character. The generated version number is displayed to the standard output (-d) file. It is also used to update the Pascal source file constant (-psource). The second SetVersion command set the 'vers',2 resource (-t 'vers', -i 2). The version is set unconditionally to 3.0b1 and the long message string to "MPW 3.0b1". MPW 3.0b1 is the MPW release, and SetVersion is just one of the files that belong to this release. The last example illustrates how both 'vers' resources should be used. The 'vers',1 resource is the individual file version while the 'vers',2 is the version release of a product that "owns" the file. The last example also should give some idea of how to arrange makefiles, specifically makefile macro definitions, to make the version numbering automatic and general. The following example illustrates this. It is the actual macro definitions and the SetVersion calls used to build SetVersion itself. They are taken as is from SetVersion’s makefile. MPWversion = 3.0b1 # product release version Copyright = ©Apple Computer, Inc. # copyright notice ver2 = MPW {MPWversion} # long msg string for 'ver',2 ver1 = ^, {Copyright} # long msg string for 'ver',1 - - - SetVersionVer = -sv 3 -r # SetVersion's component controls Stage = -stage rel -sb 0 # Stage used by tools in makefile - - - SetVersion {LinkedTools}SetVersion -psource {ToolsDir}SetVersion.p ∂ {SetVersionVer} -t vers -i 1 {stage} -d ∂ -verstring "{ver1} 1984-1988, by Ira L. Ruben" SetVersion {LinkedTools}SetVersion -version {MPWversion} -t vers ∂ -i 2 -verstring "{ver2}" - - - The macro definitions specify the common aspects of the build; that is, • {MPWVersion}—the MPW release (which can be changed by a Make -d option when Make is called). • {Copyright}—the copyright string (which is concatenated into the 'vers',1 long message string). • {ver1}—the long string for the 'vers',2 resource (note it uses the MPW release string—we could have used a "^" here), which is to be displayed at the top of the Finder’s Get Info window. • {ver2}—the long string for the 'vers',1 resource (here we do use the "^"), which is to be displayed as the tools’ individual version number (we use only version and revision numbers). • {SetVersionVer}—a macro that defines the numbering control for the individual tool (the makefile is used to make other tools so there is one of these for each individual tool made). • {Stage}—Used just to insure that only ver.rel is generated in the 'vers',1 resource. The two SetVersion calls are similar to the previous example, but here they are part of a makefile, and we use the macros. 1 Commando only uses the SetVersion string resource if a "VersionDialog" is specified as part of the Commando resources. If omitted, Commando will look for a 'vers' resource(s). 2 When Commando uses a 'vers' resource, it first will look for a 'vers' ,1 resource, and if not present, a 'vers' ,2 resource. The short version string is displayed below the Do It button. Clicking this version number causes the long version string to be displayed in the "help" box. The two 'vers' resources as well as the strings they contain are described when the 'vers' resource format is described. 3 The comparison of the BCD field is only valid if the version number components don’t exceed the limitations imposed by the resource. Specifically, the version and nonrelease values are limited to two BCD digits, while the revision and bug fix values are limited to one digit. Because of these limitations, SetVersion does not use the BCD value. SetVersion does, however, place the low-order digits of the actual version components (maintained in the short message) into the BCD fields. The BCD field is thus valid until the version counts exceed the corresponding BCD limitations. 4 See the -t option for a summary of which options are valid as a function of which resource (SetVersion’s string or Finder’s 'vers' resource) is being manipulated. 5 The country names are spelled exactly as specified in Inside Macintosh for the International Utilities. æKY Shift æC Shift -- renumber command file positional parameters Shift [number] Status codes returned: 0 Success. 1 Syntax error. Description Shift renames the command script positional parameters {number+1}, {number+2}… to {1}, {2}, and so on. If number is not specified, the default value is 1. Parameter 0 (the command name) is not affected. The variables {Parameters}, {Parameters}, and {#} variables are also modified to reflect the new parameters. Examples The following script repeats a command once for each parameter: ### Repeat - Repeat a command for several parameters ### # # Repeat command parameter… # Execute command once for each parameter in the # parameter list. You can specify options by # including them in quotes with the command name. # Set d {1} Loop Shift Break If {1} == "" {cmd} "{1}" End In the preceding example, the Shift command is used to step through the parameters. The Break command tells the loop when all the parameters have been used. You might, for example, use the following Repeat script to compile several C programs with progress information: Repeat 'C -p' Sample.c Count.c Memory.c See also "Parameters" in Chapter 5. æKY ShowSelection æC ShowSelection -- place the selection within an editor window ShowSelection [-t | -b | -c | -n lines | -l line] [window] -t # place first line of selection at top of window -b # place first line of selection at bottom of window -c # center the first line within the window -n lines # place first line of selection lines from the top -l line # place line at the top of window æKY Shutdown æC Shutdown -- power down or restart the machine Shutdown [-y | -n | -c] [-r] -y # save all modified windows (avoids dialog) -n # do not save any modified windows (avoids dialog) -c # cancel if a window needs to be saved (avoids dialog) -r # restart the machine Status codes returned: 1 Syntax error. 2 Command aborted. Note: Shutdown cannot return a status of 0 because if there are no errors the command never returns. Description Shutdown quits MPW and then either shuts down or reboots the Macintosh. The default is shutdown. Before rebooting the computer, the system executes standard quit procedures, asking for confirmation to save modified files, close all windows, and so on. • Note: Under MultiFinder, Shutdown does not give other active applications the chance to save their documents. Examples Shutdown -y Shuts down the machine, answering "Yes" to any dialogs such as those prompting to save files. See also Quit command. æKY SizeWindow æC SizeWindow -- set a window's size SizeWindow [h v] [window] h # window width (horizontal) v # window height (vertical) Status codes returned: 0 No errors. 1 Syntax error (error in parameters). 2 The specified window does not exist. 3 The h v size specified is too big. Description Sets the size of the specified window to be h by v pixels, where h and v are nonnegative integers referring to the horizontal and vertical dimensions, in that order. (Use a blank space to separate the numbers h and v on the command line.) The default window is the target (second from the front) window; a specific window can optionally be specified. If the size specified would cause the window to be too big for the screen, an error is returned. Examples SizeWindow 200 200 Makes the target window 200 pixels square in size. SizeWindow {Active} A SizeWindow command with no parameters displays the size of the specified window: SizeWindow 500 100 {Worksheet} Makes the Worksheet window 500 x 100 pixels in size. See also MoveWindow, RotateWindows, StackWindows, TileWindows, and ZoomWindow commands. æKY Sort æC Sort -- sort or merge lines of text Sort [option…] [files…] -b # skip leading blanks of each field -check # check if input is sorted (exit code 5 if not). -d # sort fields as decimal numbers -f field[,field] # specify fields to sort on (see below) -fs string # specify field separator characters -l # convert to lowercase before comparison -merge # merge pre-sorted input files -o file # specify output file, allows sorting-in-place -p # print version and progress information -quote # handle fields with quotes -stdin # place-holder for standard input (acts like a file) -r # reverse order of comparison -t # sort fields as text (default) -u # convert to uppercase before comparison -unique # write only unique output lines -x # sort fields as hexadecimal numbers (leading '$' # or '0x' is ignored) The comma-separated field specifications (following -f) take the forms: [F][.C][-K][bdlqrtux] or [F][.C][+N][bdlqrtux] 'F' is a field number (0=whole line [default], 1=first word, 2=second word…). 'C' is the starting column number (from 1), default=1. 'K' is the ending column number >= C, default=infinite. 'N' is the maximum number of characters in the field, default=infinite. Only one of '-K' or '+N' can be specified. The local modifier characters 'bdlqrtux' have the same meaning on a per-field basis as -b, -d, -l, -q, -r, -t, -u and -x (which take effect globally). Status codes returned: 0 No errors. 1 Syntax error on command line. 2 Any other error. 4 Out of memory. 5 Input is not sorted. Description Sort sorts or merges the specified files and prints the result on the standard output. If no input files are specified, standard input is assumed. Fields and Field Specifications The -f option (see "Options" ) precedes a comma-separated list of field specifications. Lines are sorted by extracting and comparing the fields in the order specified until a comparison yields inequality. If a field exists in one line but not the other, the line that possesses the field wins. If neither line has a field, the lines are considered equal. Fields not sorted are output randomly (Sort is not a stable sort). Each of the field specifications takes one of the forms: [F][.C][-K][modifiers] [F][.C][+N][modifiers] F is a field number, C and -K are column numbers, and +N is a character count. Any of the items may be omitted, provided that at least one item appears. The numbers -K and +N are mutually exclusive. Spaces can appear anywhere in the specification (except within numbers), but they must be Shell-quoted. Fields are numbered from 1. A field is a string of characters surrounded by newlines or field separator characters (usually whitespace; see the -fs option). Typically field 1 would be the first word on the line, field 2 the second word, and so on. Field 0 represents the entire line and is the default if a field number is not specified. Field separator characters are treated as normal text (not separators) in field 0. Columns are numbered from 1. If .C is specified, it represents a starting offset into the field, taking into account the (file-dependent) varying width of tab characters, if necessary. .C defaults to 1 if it is not specified. If -K is specified it represents the last column to be included in the field. It defaults to infinity (the maximum K possible) if not specified. Except for field 0, fields are always terminated by field-separator characters, so a large K does not mean "the rest of the line." If +N is specified, it represents the number of characters to be included in the field (this differs from -K in that tabs are always counted as single characters). It defaults to infinity (the maximum N possible) if not specified. Here is a short description of all possible field specifications: F The entirety of field F. F.C Columns C…∞ in field F. F.C-K Columns C…K in field F. F.C+N N characters starting at column C in field F. F-K Columns 1…K in field F. F+N The first N characters in field F. .C Columns C…∞ in the whole line. .C-K Columns C…K in the whole line. .C+N N characters starting at column C in the whole line. -K Columns 1…K in the whole line. +N The first N characters of the whole line. A field specification may be followed by one or more modifier characters: r Reverse order of comparison (reverses -r). b Ignore leading blanks (reverses -b). q Interpret quotes when extracting field (reverses -quote). d x t l u Treat field as decimal (d), hexadecimal (x), normal text (t), lowercase text (l) or uppercase text (u). These modifiers are mutually exclusive. These modifiers override the corresponding command line options on a field-by-field basis (r, q, and b flip the meaning of -r, -quote, and -b). When sorting multiple files, each file can have its own tab setting. When comparing column-aligned fields, Sort correctly handles tabs of varying width, even when comparing records from different files. Examples Sort Able -stdin Baker -o Output Sort the files Able, Baker, and the standard input, with output to file Output. Sort -x -f '2.2+8, 1tr' Frog Sort the file Frog. The first key to sort on consists of eight characters starting at the second column of the second field, treated as a hexadecimal number. The second key to sort on is merely the text of the first field, in reverse order. Sort -p -merge -u one two three infinity Merge the specified files, treating lowercase characters as uppercase. Print version and progress information. æKY StackWindows æC StackWindows -- arrange windows diagonally StackWindows [-h num] [-v num] [-r top,left,bottom,right] [-i] [windows…] -h num # horizontal offset between windows -v num # vertical offset between windows -r t,l,b,r # rectangle in which to stack windows -i # include the worksheet windows… # list of windows to tile Status codes returned: 0 No errors. 1 Syntax error (in parameters). Description Automatically sizes and moves all of the open Shell windows (except the Worksheet) so that they are staggered diagonally across the screen. Use StackWindows when selecting windows from the Window menu; this makes dealing with many open windows easier. If no windows are specified, all open Shell windows (except the Worksheet) are stacked up. Additionally you can specify the horizontal and vertical staggering constants; otherwise staggering defaults to five pixels horizontally and 20 pixels vertically. You can also include the Worksheet by using the -i option. Examples StackWindows Stacks all of the Shell windows, excluding the Worksheet, in a neat and orderly fashion. StackWindows -i -v 20 -h 10 {active} {target} Stacks the top two windows, including the Worksheet, with a vertical spacing of 20 pixels and a horizontal spacing of 10 pixels. See also MoveWindow, RotateWindow, SizeWindow, TileWindows, and ZoomWindow commands. æKY StreamEdit æC StreamEdit -- scriptable text editor StreamEdit [option…] file… -d # delete lines (don't copy them) -e statements # add 'statements' to the script -o file # direct output to file in a "safe" manner -p # print progress information -s file # specify a file containing a script to execute -set variable[=string] # set the value of a variable A script consists of zero or more of: <address> <command>… Addresses take the forms (highest to lowest precedence): ( address ) # override precedence ! address # match line not matching the address address1 && address2 # match line matching address1 AND address2 address1 || address2 # match line matching address1 OR address2 address1 , address2 # match address1…address2 /regular expression/ # a line that matches the expression • # matches BEFORE the first line N # matches the Nth line $ # matches the last line ∞ # matches AFTER the last line A regular expression starting with 'ç' is case-sensitive. Any '•' must follow the 'ç'. Commands are: Append <text> # append text to append buffer Exit [status] # exit with zero or specified status Change <text> # set contents of edit buffer Delete # clear contents of edit buffer Insert <text> # append text to insert buffer Next # proceed with next line Print <text> # Print the text [-To file ] # directed to the specified file [-AppendTo file] # appended to the specified file Replace /pat/ <text> # do replacement [-c count] # specify repeat count (N or ∞) Set variable <text> # set variable's value [-a] # append to variable's current value [-i] # insert at front of variable's current value Option AutoDelete # append "1,$ Delete" to script Where <text> consists of zero or more of: "a string" # the specified text 'a string' # the specified text . # the current line (the edit buffer) variableName # the contents of the named string variable ®N # an "®" variable set by a regular expression -from <filename> # the next line from the file, where filename # is a string or a variable name -n # suppress newline at end If <text> is empty, it defaults to "." (the current line). Description StreamEdit is an "offline" text editor similar to the Unix™ tool sed; it provides scriptable text matching and editing operations. [It is not compatible with Unix™ sed or awk]. It is useful for making repetitive changes to files, for extracting information from text files, or as a filter. StreamEdit takes a script and a set of input files (or standard input, if no input files are specified) and applies each statement in the script to each line of input, writing the output to standard output or the specified output file. The script is specified by one or more -e or -s options. If more than one script is specified, the resulting script is the concatenation of all the scripts. If no script is specified (and -d is not specified), the script effectively defaults to 1,$ Print which has the effect of simply copying the input lines to the output. A script consists of a series of statements of the form: address-expression command [ ; command … ] Commands are separated by newlines or semi-colons. All the commands following a particular address, up to the next address, are executed when the address matches. A command takes the form: command-name [ text-arguments … ] Arguments are terminated by newlines and semi-colons (while addresses may span multiple lines). Address expressions, commands and command arguments are described below. Empty lines are legal. Comments begin with a sharp sign (#). Semi-colons are equivalent to line breaks (unless they appear as the first character on a line), as in the Shell, and are used to terminate commands. Newlines (outside of strings) may be escaped to extend an argument list. If a script line contains a semi-colon in the first column, the entire line is treated as a comment by StreamEdit. This allows you to write StreamEdit scripts that also contain MPW shell commands. See the Examples section for more details. Examples Extracting the Leaf Part of a File Name It is sometimes necessary to extract the leaf part of a complete file path name in a Shell script. The StreamEdit expression: /(≈:)*([¬:]*)®1/ sets the variable ®1 to the part of the file name following the last colon, or the whole file name if there it doesn't contain a colon. It could be used in a Shell script as a filter: # {MPW}Scripts:FilterLeaf StreamEdit -d -e '/(≈:)*([¬:]*)®1/ print ®1' For example: Echo "The:I:Is:Silent:myFile" | FilterLeaf would print: myFile Generating Inlines This is a script that generates MPW C or C++ inline function declarations from assembly language source. It's far easier and less error-prone than hand-assembly or cut-and-paste; even though this script depends on the format of the listing file produced by the MPW Assembler, it is better to automate the process. The script's usage is: MakeCInline assemblyfile.a >outputFile Given assembler input something like this: ;+ ; Inline Pascal string copy ; ;¥ void pascal_string_copy(char* src, char* dest); ; ;- proc movem.l (SP),A0-A1 moveq #0,D0 move.b (A1),D0 bra.s @2 @loop: move.b (A1)+,(A0)+ @2: dbra D0,@loop endproc We want the filter to produce an inline declaration something like this: void pascal_string_copy(char* src, char* dest) = {0x4cef, 0x0300, 0x6b00, 0x1011, 0x6002, 0x10d9, 0x51c8, 0xfffc}; The character '¥' in the assembler comment marks the declaration; in principle any unique character or string can be used to flag the declaration. The script has two parts; the first part contains MPW Shell commands, the rest of the script contains StreamEdit statements. The MPW Shell part of the script is: # MakeCInline -- make C assembly language inline declarations ; asm "{1}" -l ; StreamEdit -d -s "`which {0}`" "{1}".lst ; Delete "{1}".lst "{1}".o ; exit It runs the assembler on the input file, producing a listing which is processed by the rest of the script. Then the temporary files are removed and the MPW Shell part of the script exits; the Exit command ensures that the Shell doesn't execute any StreamEdit statements. The invocation of StreamEdit here has an interesting hack; the name of the StreamEdit script to execute is, naturally, the name of the currently executing script. So we use `which {0}` which expands into the name of the currently running shell script. The rest of the file contains a StreamEdit script that processes the assembly listing produced above. Here's an example of the assembler's listing output: MC680xx Assembler - Ver 3.2d1 21-Nov-89 Page 1 Copyright Apple Computer, Inc. 1984-1989 Loc F Object Code Addr MSource Statement case on ;+ ; ; ¥ void pascal_string_copy(char* src, char* dest) ; ;- 00000 strcpy proc export 00000 4CD7 0300 movem.l (SP),A0-A1 00004 7000 moveq #0,D0 00006 1011 move.b (A1),D0 00008 6002 0000C bra.s @1 0000A 10D9 @loop: move.b (A1)+,(A0)+ 0000C G 51C8 FFFC 0000A @1: dbra D0,@loop 00010 endproc end Elapsed time: 0.08 seconds. Assembly complete - no errors found. 16 lines. The opcodes we need are tantalizingly close … but embedded in goop that we need to strip away. The first job is to extract the inline's declaration and copy it to the output. Hex constants must be separated by commas — we accomplish this with a variable, initially empty, that is set to a comma-and-space when a hex constant is emitted, so that a comma precedes every hex constant but the first one. /;¥[ ∂t]*([¬;]*)®1/ Print -n ®1 " =∂n{" Set PRECEEDING_COMMA "" Delete The regular expression matches the inline declaration in the comment (which can be recognized by virtue of the marker string — "¥" — that we put there). The text of the inline is extracted, omitting a possible trailing semicolon, and put into the variable ®1. The Print statement emits the inline declaration (in ®1) and extra stuff needed for C inline syntax. The PRECEEDING_COMMA variable is set to empty, the line is deleted, and processing continues. The inline declaration is terminated by an ENDP or an ENDPROC assembler directive: /[ ∂t]ENDP/ Print "};∂n" Delete Next, totally uninteresting lines are deleted. Examining the assembly listing, we note that the lines with the object code we need invariably contain a hex constant starting in the first column, several spaces (with an optional "G"), and at least one two-byte hex constant. We'll strip every line that doesn't meet these criteria, so there will be less noise to worry about. !/•[0-9a-f]+ [ g] [0-9a-f]«4»/ Delete Then we simply delete any junk that precedes the hex constant we're interested in: 1,$ Replace /[0-9a-f]+ [g ] / "" Now the line contains one word of assembler output that we can copy to the output: /•([0-9a-f]«4»)®1 / Print -n PRECEEDING_COMMA "0x"®1 Set PRECEEDING_COMMA ", " Replace // "" We print an optional comma, followed by the hex constant itself. Then we arrange for future constants to be preceded by a comma, and remove the constant from the front of the line. Now we have a problem — there's no way to tell how many more constants have to be processed. Furthermore, StreamEdit has no control structures for looping, so a count wouldn't help much anyway. So we resort to a hack, namely, repeating the above code as many times as we're likely to ever need it for a single line of assembler output. # # Convert remaining words # (I wish StreamEdit had looping!) # /•([0-9a-f]«4»)®1 / Print -n ", 0x"®1 Replace // "" /•([0-9a-f]«4»)®1 / Print -n ", 0x"®1 Replace // "" /•([0-9a-f]«4»)®1 / Print -n ", 0x"®1 Replace // "" /•([0-9a-f]«4»)®1 / Print -n ", 0x"®1 Replace // "" Examination of the assembler output shows that handling five constants on a line is more than enough. However, if the assembler listing format changes, the script will break. Unpacking Unix Shell Archives This script unpacks a Unix shell archive, more commonly known as a shar file. Shar files are used in the Unix community to gather text (say, the sources for a program, including its makefile) into a single file, suitable for transmittal by electronic mail or usenet. Shar files typically have the form: garbage at the beginning — mail headers and so forth sed "s/^X//" >TheFile <<'END_OF_TheFile ' Xtext of the file X where each line X is preceded by an 'X' END_OF_TheFile more files, similarly packed The Unix shell and the tool sed cooperate to strip off the 'X's at the beginning of each line, and to direct the output to the correct file. Unfortunately the MPW Shell does not have this kind of redirection, and StreamEdit is not sed, so we have to come up with our own solution. To make matters worse, there is no single format for a shar file — in the Unix community it's "anything goes", as long as the standard Unix tools can unpack it. A StreamEdit script to unpack an arbitrary shar file would have to closely emulate the Unix environment, which is rather difficult. In practice, you'll have to tweak this script to handle different kinds of shar files. The script starts with the usual MPW Shell commands to start up StreamEdit with the proper script, pass along the command-line parameters, and exit. No surprises: ; streamedit -d -s `which "{0}"` {parameters} ; exit The variable FILE holds the name of the current output file. When we see a line beginning with "sed", we extract the output filename (possibly enclosed in quotes) and put it in the variable. • Set FILE "DELETE.ME" # for safety's sake /•sed/ && ( />[ ∂t]*∂'([¬ ∂t]*)®1∂' / # sed … >'quotedFile' || />[ ∂t]*([¬ ∂t>]*)®1 / # sed … >notQuotedFile ) Set FILE ®1 print "Extracting " FILE For paranoia's sake, the FILE variable is initialized to "DELETE.ME", and the name of each file extracted is printed on standard output. Extraction is simple — for every line beginning with an "X", the "X" is stripped off and the line is written to the current destination file. /•X/ replace // "" print -to FILE See also Shell documentation on regular expressions. æKY Target æC Target -- make a window the target window Target name Status codes returned: 0 No errors. 1 Error in parameters. 2 The specified file does not exist. 3 System error. Description Makes window name the target window for editing commands (that is, the second window from the front). If window name isn’t already open, then file name is opened as the target window. If name doesn’t exist, an error is returned. Examples Target Sample.a Makes the window Sample.a the target window. See also Open command. "Editing With the Command Language" in Chapter 5. æKY TileWindows æC TileWindows -- arrange windows in a tiled fashion TileWindows [-h | -v] [-r top,left,bottom,right] [-i] [windows…] -h # tile windows horizontally -v # tile windows vertically -r t,l,b,r # rectangle in which to tile windows -i # include the worksheet windows… # list of windows to tile Status codes returned: 0 No errors. 1 Syntax error (error in parameters). Description TileWindows automatically sizes and moves the specified Shell windows so that they are all visible on the screen at once. If no windows are specified, all open windows are tiled (except the Worksheet). Arranging your open windows like tiles and then zooming a selected window to full size makes dealing with many open windows much easier. Examples TileWindows Arranges all of the Shell windows in a tile pattern, so that all are visible. TileWindows -h hd:new:main.c hd:new:foo.c Arranges the specified windows as two long horizontal strips. TileWindows -v {active} {target} Arranges the top two windows vertically. See also MoveWindow, RotateWindow, SizeWindow, StackWindows, and ZoomWindow commands. æKY TransferCkid æC TransferCkid -- move Projector information from one file to another TransferCkid sourceFile destinationFile Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. Description Move the Projector 'CKID' resource from sourcefile to destinationfile. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. æKY Translate æC Translate -- translate characters Translate [-p] [-s] src [dst] < file > output ≥ progress -p # write progress information to diagnostics -s # set font, font size, and tab setting of output Status codes returned: 0 Normal termination. 1 Parameter or option error. Description Standard input is copied to standard output, with input characters specified in the src (source) parameter string mapped into the corresponding characters specified by the dst (destination) parameter string; all other characters are copied as is. If dst is omitted, all characters represented by the src are deleted. If the dst string is shorter than the src, all characters in the src that would map to or beyond the last character in the dst are mapped into the last character in dst, and adjacent instances of such characters in the input are represented by a single instance of the last character in dst. Both src and dst are specified as a standard Shell character list but not enclosed in square brackets. Thus the src and dst are sequences of one or more characters (that is, an abcde) or a range of characters separated by a minus sign (that is, a–z, 0–9). Standard escape characters (such as , • Note: Case sensitivity of letters specified in the src list are governed by the {CaseSensitive} Shell variable. If CaseSensitive is set to 1, then only letters specified in the src are mapped or deleted. If CaseSensitive is 0, then uppercase and lowercase letters not explicitly mapped into dst characters are mapped identically. Examples translate a-z A-Z <origFile >ucFile Converts all lowercase letters in origFile to uppercase and writes the translated file to ucFile. translate 0-9 9 <origFile >outFile Converts each string of digits in origFile to the single digit 9 in outFile. translate Converts each run of blanks, tabs, or newline (return) characters in origFile to a single newline character in outFile. This effectively produces an output with just one word on each line. Note that the src string had to be quoted to specify the blank. translate ¬a-zA-Z <origFile >outFile Removes all punctuation and isolates words by spaces on each line. Here we negated the src character list. Thus all characters except letters and newline characters are replaced with spaces. æKY Unalias æC Unalias -- remove aliases Unalias [name…] Status codes returned: 0 no errors. Description Removes any alias definition associated with the alias name. (It is not an error if no definition exists for name.) s Caution If no names are specified, all aliases are removed. s The scope of the Unalias command is limited to the current script; that is, aliases in enclosing scripts are not affected. If you are writing a script that is to be completely portable across various users’ configurations of MPW, you should place the command Unalias at the beginning of your script to make sure no unwanted substitutions occur. Examples Unalias File Remove the alias "File". (This alias is defined in the Startup file.) See also Alias command. "Command Aliases" in Chapter 5. æKY Undo æC Undo -- undo the last edit Undo [window] Status codes returned: 0 No errors. 1 Syntax error (error in parameters). 2 Any other error. Description Undo is the scriptable equivalent of choosing Undo from the Edit menu to reverse the last editing operation. Undo without any parameters acts on the target (that is, the second from the front) window. Optionally a named window can be specified. • Note: Remember that Undo is maintained on a window-by-window basis. Therefore using this command will undo the last edit operation that was performed in the specified window, which may or may not be the last operation actually performed. Examples Undo Reverses the last edit operation in the target window. Undo {Worksheet} Reverses the last edit operation in the Worksheet window. See also Cut, Copy, and Paste commands. æKY Unexport æC Unexport -- remove variable definitions from the export list Unexport [-r | -s | name…] > unexports -r # generate Export commands for all unexported variables -s # print the names only Status codes returned: 0 No error. 1 Syntax error. Description Removes the specified variables from the list of exported variables. The list of exported variables is local to a script, so unexported variables are removed only from the local list. If no names are specified, a list of unexported variables is written to standard output. The default output of Unexport is in the form of Unexport commands. (A variable that is not exported is considered unexported.) Examples Set SrcDir HD:source: Export SrcDir # SrcDir is available to scripts and tools … Unexport SrcDir Now the variable SrcDir is no longer available to scripts and tools. Unexport -r Export var1 Export var2 … This example lists all the variables that are not exported. To export them, simply select and execute all the export commands. To get a list of all the variables that have not been exported, execute this command: Unexport -s var1 var2 ... varx See also Set and Export commands. æKY Unmark æC Unmark -- remove a marker from a window Unmark name… window Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Unmark removes the marker(s) name… , from the list of markers available for window. When a window is the current active window, the Mark menu item(s) will be adjusted. Examples Unmark `Markers` {Target} Removes all markers associated with the target window. Unmark Proc1 {Active} Removes the "Proc1" marker from the active window’s marker list. Because {Active} is by definition the current active window, the Mark menu is also adjusted to reflect the deletion of the "Proc1" marker. Limitation Unmark does not support Undo. See also "Markers" in Chapter 6. æKY Unmount æC Unmount -- unmount volumes Unmount volume… Status codes returned: 0 The volume was successfully unmounted. 1 Syntax error. 2 An error occurred. Description Unmounts the specified volumes. A volume name must end with a colon ( : ). If volume is a number without a colon, it’s interpreted as a disk drive number. The unmounted volumes cannot be referenced again until remounted. If you unmount the current volume (the volume containing the current directory), the boot volume becomes the current volume. Examples Unmount Memos: Unmounts the volume titled Memos. Unmount 1 2 Unmounts the volumes in drives 1 (the internal drive) and 2 (the external drive). (The command Eject 1 2 would unmount and eject the volumes.) See also Eject and Mount commands. æKY UnmountProject æC UnmountProject -- unmount projects UnmountProject -a | Project… -a # unmount all mounted projects Status codes returned: 0 No errors. 1 Syntax error. 2 Error in processing. 3 System error. Description Unmount projects mounted under Projector. See Chapter 7 of the MPW manual for complete definitions of the terms and symbols used in Projector commands. Examples To unmount all mounted projects use: UnmountProject -a To unmount the projects MyProject and YourProject use: UnmountProject MyProject YourProject See also MountProject. æKY Unset æC Unset -- remove Shell variable definitions Unset [name…] Status codes returned: 0 no errors. Description Removes any variable definition associated with name. (It’s not an error if no definition exists for name.) • Caution If no names are specified, all variable definitions are removed. This can have serious consequences. For example, the Shell uses the variable {Commands} to locate utilities and applications and uses several other variables to set defaults. The assembler and compilers use variables to help locate include files. (For details, see "Variables Defined in the Startup File" in Chapter 5 of the MPW manual.) The scope of the Unset command is limited to the current script; that is, variables in enclosing scripts are not affected. Examples Unset CaseSensitive Removes the variable definition for {CaseSensitive}. This turns off case-sensitive searching for the editing commands. See also Set, Export, and Unexport commands. "Defining and Redefining Variables" in Chapter 5. æKY UserVariables æC UserVariables -- uses Commando to set all the user variables æKY Version æC Version -- print the version of the MPW Shell æKY Volumes æC Volumes -- list mounted volumes Volumes [-l] [-q] [volume…] > volumeList -l # long format (name, drive, size, free, files, dirs) -q # don't quote volume names with special characters Status codes returned: 0 No errors. 1 Syntax error. 2 No such volume. Description For each volume named, Volumes writes its name and any other information requested to standard output. The output is sorted alphabetically. A volume name must end with a colon ( : )—if volume is a number without a colon, it’s interpreted as a disk drive number. If volume is not given, all mounted volumes are listed. Examples Volumes -l will write information such as Name Drive Size Free Files Dirs _____ ______ _____ _____ ______ _____ HD: 3 19171K 14242K 290 33 Files `Volumes 1` Lists the files on the disk in drive 1 (the built-in 3.5-inch disk drive). æKY WhereIs æC WhereIs -- find the location of a file WhereIs [-c] [-d] [-v] [-s directory]… pattern -c # completely match filepattern -d # include directories -v # verbose output - put summary line at end -s directory # starting directory/volume for search Status codes returned: 0 No errors. 1 Syntax error. 2 File system error during processing. 3 No matches were found. Description Use WhereIs to find the location of all files that contain pattern as part of their filename. You can use WhereIs to find files hidden in the directory tree. Pattern is a full or partial filename. For example, a pattern of "test" will match TestProg.c, test.c, and Work:OutputTest. WhereIs starts searching in the root directory of the default volume and searches the entire disk. To constrain the search to a portion of a disk, or to specify different disks or multiple disks, use the -s option. To list any directories that contain pattern, use the -d option. To constrain the search to files that completely match pattern, use the -c option. The -v option prints the number of items matched with pattern. Matching is not case sensitive, and regular expressions are not supported. WhereIs lists the full pathname of all files and directories found. Files that contain special characters are quoted. Examples WhereIs test Find all files that have "test" in their filename. The output would be something like HD:MPW:test.c HD:MPW:test.c.o HD:MPW:TestMenu.c HD:MPW:TestProg.p WhereIs -c test.c Find files named test.c. The output (with the same files as the example above) would be HD:MPW:test.c WhereIs -d test Find all files or directories that have "test" in their leafname. The output would be HD:MPW:TestDir: HD:MPW:test.c HD:MPW:test.c.o HD:MPW:TestMenu.c HD:MPW:TestProg.p WhereIs -s HD:MPW -s Disk2:Work test Find all files that have "test" in their pathname. Search for the files starting in HD:MPW and also in Disk2:Work. æKY Which æC Which -- determine which file the shell will execute Which [-a] [-p] [name] > file ≥ progress -a # report all commands named "name" -p # writes progress information to diagnostics Status codes returned: 0 No error. 1 Syntax error. 2 Command not found. 3 Other error. Description Determines which command the Shell will execute when command is entered. Which looks for commands defined by aliases, Shell built-in commands, and commands accessible through the Shell variable {Commands} (the same order the Shell uses). If command is not specified, all paths in the {Commands} variable will be written to standard output, one directory per line. The directories are listed in the order in which the Shell would search for commands. In this case the -a and -p options have no meaning. Examples Which asm This command outputs something like - HD:MPW:Tools:asm. The Shell then executes hd:MPW:Tools:asm when given asm. Which -a makeit Alias makeit 'make > tmp; tmp' HD:MPW:Tools:makeit HD:MPW:Scripts:makeit In this case, there are three different "makeit" commands that the Shell could execute, as determined by current aliases and the {Commands} variable. The Shell executes the first one found (the alias). Which newfolder newfolder In this case, newfolder is a Shell built-in command. æKY Windows æC Windows -- list windows Windows [-q] -q # don't quote window names with special characters -o # list "Open" command lines for execution Status codes returned: 0 No error. 1 Syntax error. Description Writes the full pathname of each file currently in a window. The names are written to standard output, one per line, from backmost to frontmost. Examples Windows Lists the pathnames of all open windows. Print {PrintOptions} `Windows` Prints the pathnames of the open windows, using the options specified by the {PrintOptions} variable. This example uses command substitution: Because the Windows command appears in backquotes (`…`), its output supplies the parameters to the Print command. Echo "Open `Windows` || Set Status 0" > SavedWindows Writes a script in the file SavedWindows that will reopen the current set of open windows. Notice how Echo is used to create the script. The conditional || execution operator restores the status to zero should an error occur while opening the remembered windows. This technique is used in the script Suspend to save the list of open windows. æKY ZoomWindow æC ZoomWindow -- enlarge or reduce a window's size ZoomWindow [-b | -s] [window] -b # zoom to full screen (big) -s # zoom back to regular size (small) Status codes returned: 0 No errors. 1 Syntax error (error in parameters). 2 The specified window does not exist. Description Zooms the specified window according to the option specified. The default window is the target (second from the front) window; a specific window can optionally be specified. The -s option forces the window to zoom back to its small size. The -b option forces the window to zoom to its full size. If no option is specified, the window toggles to the other size. ZoomWindow without any options mimics the operation of clicking in the window’s zoom box. This command is especially valuable when used in conjunction with StackWindows or TileWindows. Examples ZoomWindow Zooms the target window to full screen size if the window was originally in the small size. ZoomWindow -s {Worksheet} Zooms the Worksheet window back to its small size. See also MoveWindow, RotateWindows, SizeWindow, StackWindows, and TileWindows commands. {ZoomWindowRect} variable in Chapter 5. The "full size" window is normally the entire screen. You can change it (for example, prevent it from covering the disk and trash icons) by specifying a rectangle in the Shell variable {ZoomWindowRect}.